You are on page 1of 282

May 14, 2012

Edge Server Configuration


Guide
Akamai Conf idential. Non-Disclosure Agreement Required

Akamai Technologies, Inc
Akamai Customer Care: 1-877-425-2832 or, for routine requests, email ccare@akamai.com
The EdgeControl Management Center, for customers and resellers: http://control.akamai.com
Edge Server Configuration Guide (version 6.4.0)
Copyright 20022012 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 Headquarters
8 Cambridge Center
Cambridge, MA 02142
Tel: 617.444.3000
Fax: 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
Edge Server Configuration Guide 5/14/12 3
Preface 9
Chapter 1 Conditions: Defining the Scope of Features 13
Host Header or In-ARL Hostname........................................................ 14
Directory Path ..................................................................................... 15
Filename............................................................................................. 16
Filename Extension.............................................................................. 17
Request URL Sub-string (uri.wildcard) .................................................. 18
ARL Type............................................................................................. 19
Client IP .............................................................................................. 20
Client Request Completion.................................................................. 21
Client Cookies..................................................................................... 22
Client SSL............................................................................................ 23
Client StatusCode Served................................................................... 24
Client Timeout .................................................................................... 25
Content Provider Code........................................................................ 26
EdgeScape Data.................................................................................. 27
Extracted Value................................................................................... 29
Fail-Action Attempt ............................................................................. 30
Fragment Request ............................................................................... 31
Forward-Rate-Limit Blocked Request ................................................... 32
Protocol .............................................................................................. 33
Query String Arguments...................................................................... 34
Referrer Denied................................................................................... 35
Request Headers................................................................................. 36
Request M ethod ................................................................................. 37
Request Type ...................................................................................... 39
Response Headers............................................................................... 40
Response Status.................................................................................. 41
Serving From Cache Only.................................................................... 42
Time Intervals...................................................................................... 43
Typecode............................................................................................ 44
Random.............................................................................................. 45
Receipt................................................................................................ 46
Variable Value and Variable-Error ........................................................ 47
Contents
4 Akamai Technologies, Inc.
Contents
Chapter 2 Caching 49
About Caching and Caching Terms..................................................... 51
Default Caching Behaviors.................................................................. 52
A Quick Reference to Caching Topics.................................................. 54
Cacheable Responses.......................................................................... 55
Uncacheable Content (no-store and bypass-cache) .............................. 61
Cache Control Time-To-Live (TTL) ..................................................... 63
Honor HTTP Cache-Control:max-age and ExpiresHeaders................... 66
Scheduled Invalidation ........................................................................ 70
Require Revalidation ........................................................................... 72
Zero-TTL Content................................................................................ 73
AsynchronousRefresh (prefresh) ......................................................... 75
Chapter 3 Caching - Advanced 79
Entity Tag Validation Support.............................................................. 80
Cache POST Responses....................................................................... 82
Limiting Refresh Requeststo the Origin............................................... 83
Error Response Time To Live (Negative TTL) ......................................... 84
Preserve Stale Object on Error Response Codes................................... 85
Cache 302 Responsesby Default ........................................................ 86
Quick If-M odified-Since Response....................................................... 87
Serve Only If Cached........................................................................... 88
Chapter 4 Downstream Caching 89
Default Behaviors................................................................................ 90
Controlsfor Downstream Cacheability................................................ 91
Configuration Options- Static Content ............................................... 94
Configuration Options- Dynamic Content .......................................... 96
Busting Downstream Caches............................................................... 97
Overriding Cache-busting Behaviors.................................................... 99
Chapter 5 Cache Key Modification 101
The Default Cache Key...................................................................... 102
Ignore Query String........................................................................... 104
Ignore Query Arguments................................................................... 105
Ignore Path Components.................................................................. 108
Ignore Path Parameters..................................................................... 110
Ignore Case in Cache Key................................................................. 112
Flexible Cache ID.............................................................................. 113
Chapter 6 Enhanced Availability 117
Failover (wasAdvanced Default Content) .......................................... 118
Custom Error Pages.......................................................................... 123
M onitor Origin Server ....................................................................... 125
SureRoute for Failover....................................................................... 127
Request Queuing .............................................................................. 128
Edge Server Configuration Guide 5/14/12 5
Contents
Chapter 7 Auth - Browser to Edge 131
General AccessControl ..................................................................... 132
Referrer Checking............................................................................. 133
Block Accessby Client IP ................................................................... 135
Centralized Authorization ................................................................. 136
Remote Authorization....................................................................... 138
Edge Authorization - Cookie-Based................................................... 141
Edge/Central Hybrid Authorization.................................................... 145
Edge Authorization - URL-Based - Origin Tokens............................... 146
Edge Authorization - URL-Based - Edge Server Tokens....................... 151
Chapter 8 Auth: Edge to Origin 157
Set User Agent.................................................................................. 158
Akamai-ID Cookie............................................................................. 159
Signature Header Authentication ...................................................... 160
SSL Client Certificate Authentication................................................. 162
Chapter 9 Edge Computing 165
Edge Side Includes............................................................................ 166
EdgeAkamaizer................................................................................. 167
ProcessPOST Body Through DCA ...................................................... 169
DCA Output Caching........................................................................ 170
Chapter 10 Edge Services - General 173
Add, Pass, or Remove Headers.......................................................... 174
Cloning HTTP Headers...................................................................... 175
Forward StatusCode Override........................................................... 176
Client StatusCode Override.............................................................. 177
Custom Client IP Header ................................................................... 178
Constructed Response ...................................................................... 179
Support for 100 Continue Responses................................................ 181
Support for WebDAV Requests/ Responses....................................... 182
EdgeScape - Content Targeting......................................................... 185
Chapter 11 EdgeServices - Cookie Handling 187
CookiesSet by the Origin.................................................................. 189
Generate Unique Cookies................................................................. 191
Set Explicit Cookie Via Configuration File .......................................... 193
Expire Browser Cookies(Beta) ........................................................... 194
Chapter 12 EdgeServices - Redirect Handling 195
Redirect Chasing............................................................................... 196
Generate RedirectsBased on URL M arker.......................................... 198
Generate RedirectsBased On Configuration...................................... 200
Chapter 13 Performance 203
Support Compressed Content ........................................................... 204
Last M ile Accelerator......................................................................... 205
6 Akamai Technologies, Inc.
Contents
Chunked Encoding ........................................................................... 208
Prefetching ....................................................................................... 210
Chapter 14 Forward Server 213
General Forward Connection Settings............................................... 214
Host Header M odification ................................................................. 217
Origin Server Assignment .................................................................. 218
Tiered Distribution ............................................................................ 219
SureRoute for Performance............................................................... 220
Site Shield......................................................................................... 222
Chapter 15 Forward Path 225
Prune or M odify Query String............................................................ 226
Path M odification By Rule................................................................. 227
Path M odification by Regular Expression ........................................... 228
Chapter 16 Network 229
DNS.................................................................................................. 230
HTTP................................................................................................ 231
ICP.................................................................................................... 232
Persistent Connections(pconns) ........................................................ 233
TCP Optimizations............................................................................ 235
Timeouts........................................................................................... 237
Adaptive Connect Timeout (Beta) ...................................................... 238
Client-Side Traffic Shaping (Beta) ...................................................... 240
Chapter 17 Reporting 241
Log Delivery...................................................................................... 242
Edge Logging (Download Receipts) ................................................... 245
Chapter 18 Security Related Features 249
Support POST Requests..................................................................... 250
Support for PUT and DELETE M ethods.............................................. 251
M unged URL..................................................................................... 252
Object ID Checking........................................................................... 253
Authenticate Object ID' s................................................................... 255
Use SSL Going Forward..................................................................... 256
Chapter 19 Using Variables 257
VariablesSyntax................................................................................ 258
Extracting ValuesInto Variables......................................................... 260
Assigning and Transforming Variables............................................... 262
Comparing Variables......................................................................... 265
Chapter 20 Other Capabilities 267
Session ID Support ............................................................................ 268
Download M anager.......................................................................... 271
Progressive Download Seeking.......................................................... 272
Edge Server Configuration Guide 5/14/12 7
Contents
Chapter 21 Related Services 273
NetStorage ....................................................................................... 274
Glossary 275
8 Akamai Technologies, Inc.
Contents
Edge Server Configuration Guide 5/14/12 9
In This Pref ace
Pref ace
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 providers
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.
Audience 10
Current Version 10
New Material in This Version 10
Pricing 11
Document Conventions 11
Organization 11
Related Documents 12
10 Akamai Technologies, Inc.
Pref ace
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.
Current
Version
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. Youll 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,
ht t ps: / / cont r ol . akamai . com, or ask your Akamai contact.
New Material
in 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
Conf iguration
Manager
Support
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. Youll 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.
Edge Server Configuration Guide 5/14/12 11
Conf idential & 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.
Document
Conventions
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 doesnt 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 youll 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.
12 Akamai Technologies, Inc.
Pref ace
Related
Documents
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, ht t ps: / /
cont r ol . akamai . com.
Time-to-Live in Cache: Methods and Considerations
Handling of Edge-Control & Other HTTP Headers
ESI Developers Guide
Content Control Utility Users Guide
Akamai Log Delivery Service: Service Description & Customer Technical Guide
Session ID Support
Freeflow Typecode Guide
Edge Server Configuration Guide 5/14/12 13
In This Chapter
1
Conditions: Def ining the Scope
of Features
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.
Host Header or In-ARL Hostname 14
Directory Path 15
Filename 16
Filename Extension 17
Request URL Sub-string (uri.wildcard) 18
ARL Type 19
Client IP 20
Client Request Completion 21
Client Cookies 22
Client SSL 23
Client Status Code Served 24
Client Timeout 25
Content Provider Code 26
EdgeScape Data 27
Extracted Value 29
Fail-Action Attempt 30
Fragment Request 31
Forward-Rate-Limit Blocked Request 32
Query String Arguments 34
Referrer Denied 35
Request Headers 36
Request Method 37
Request Type 39
Response Headers 40
Response Status 41
Serving From Cache Only 42
Time Intervals 43
Typecode 44
Random 45
Receipt 46
Variable Value and Variable-Error 47
14 Akamai Technologies, Inc.
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 or i gi n. example.com serves content for the
hostnames example.com and exampl e2. com, features can be applied to the two
hostnames either equally or differently depending on how the configuration file is
organized.
Edge Server Configuration Guide 5/14/12 15
Directory Path Confidential & 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.
16 Akamai Technologies, Inc.
Chapter 1: Conditions: Defining the Scope of Features
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 doesnt 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).
Edge Server Configuration Guide 5/14/12 17
Filename Extension Confidential & 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 .j sp 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 . ht ml
Log cookies for all files of type . zi p in the directory www. exampl e. com/
downl oads/ secur e/
18 Akamai Technologies, Inc.
Chapter 1: Conditions: Defining the Scope of Features
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.
Edge Server Configuration Guide 5/14/12 19
ARL Type Confidential & 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.
20 Akamai Technologies, Inc.
Chapter 1: Conditions: Defining the Scope of Features
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.
Edge Server Configuration Guide 5/14/12 21
Client Request Completion Confidential & 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.
22 Akamai Technologies, Inc.
Chapter 1: Conditions: Defining the Scope of Features
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
Edge Server Configuration Guide 5/14/12 23
Client SSL Confidential & 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 SSL
Version
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 SSL
Cipher
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 Cipher
Name
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 Cipher
Algorithm
You can match on the name of the encryption algorithm the client is using.
SSL Cipher
MAC
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.
24 Akamai Technologies, Inc.
Chapter 1: Conditions: Defining the Scope of Features
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.
Edge Server Configuration Guide 5/14/12 25
Client Timeout Confidential & 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.
Technical
Details
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).
26 Akamai Technologies, Inc.
Chapter 1: Conditions: Defining the Scope of Features
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.
Edge Server Configuration Guide 5/14/12 27
EdgeScape Data Confidential & Proprietary
EdgeScape Data
EdgeScape is an IP intelligence service. It leverages Akamais 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 Akamais
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.
Technical
Details
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
28 Akamai Technologies, Inc.
Chapter 1: Conditions: Defining the Scope of Features
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.
Edge Server Configuration Guide 5/14/12 29
Extracted Value Confidential & 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.
30 Akamai Technologies, Inc.
Chapter 1: Conditions: Defining the Scope of Features
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.
Edge Server Configuration Guide 5/14/12 31
Fragment Request Confidential & 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.
32 Akamai Technologies, Inc.
Chapter 1: Conditions: Defining the Scope of Features
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.
Technical
Details
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.
Edge Server Configuration Guide 5/14/12 33
Protocol Confidential & Proprietary
Protocol
Akamai servers can apply features based on whether the request was made using
HTTPS: or HTTP: as the protocol.
34 Akamai Technologies, Inc.
Chapter 1: Conditions: Defining the Scope of Features
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.
Edge Server Configuration Guide 5/14/12 35
Referrer Denied Confidential & Proprietary
Ref errer 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 clients
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.
36 Akamai Technologies, Inc.
Chapter 1: Conditions: Defining the Scope of Features
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.
Edge Server Configuration Guide 5/14/12 37
Request Method Confidential & 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 Akamais 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:
GET
HEAD
POST - must be enabl ed ( secur i t y: al l ow- post )
PUT - must be enabl ed ( secur i t y: al l ow- put )
38 Akamai Technologies, Inc.
Chapter 1: Conditions: Defining the Scope of Features
HTTP_DELETE - must be enabl ed ( secur i t y: al l ow- del et e)
OPTI ONS - must be enabl ed ( edgeser vi ces: webdav. st at us)
WebDAV Methods
These methods are available with WebDAV support has been enabled through
edgeservices:webdav.status
DAV_COPY
DAV_PROPFI ND
DAV_PROPPATCH
DAV_MKCOL
DAV_MOVE
DAV_LOCK
DAV_UNLOCK
Edge Server Configuration Guide 5/14/12 39
Request Type Confidential & 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).
40 Akamai Technologies, Inc.
Chapter 1: Conditions: Defining the Scope of Features
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.
Technical
Details
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.
Edge Server Configuration Guide 5/14/12 41
Response Status Confidential & 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.
42 Akamai Technologies, Inc.
Chapter 1: Conditions: Defining the Scope of Features
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.
Edge Server Configuration Guide 5/14/12 43
Time Intervals Confidential & 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. :
UTC
US/ Cent r al
US/ East er n
US/ Mount ai n
US/ Paci f i c
Asi a/ 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:
Eur ope/ London
Eur ope/ Par i s
WET
CET
MET
EET
I sr ael
Aust r al i a/ Sydney
Aust r al i a/ Per t h
Asi a/ Tokyo
44 Akamai Technologies, Inc.
Chapter 1: Conditions: Defining the Scope of Features
Typecode
This condition tag makes it possible to apply features to requests made using a
FreeFlow ARL with a particular typecode.
Edge Server Configuration Guide 5/14/12 45
Random Confidential & 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.
46 Akamai Technologies, Inc.
Chapter 1: Conditions: Defining the Scope of Features
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.
Edge Server Configuration Guide 5/14/12 47
Variable Value and Variable-Error Confidential & 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.
48 Akamai Technologies, Inc.
Chapter 1: Conditions: Defining the Scope of Features
Edge Server Configuration Guide 5/14/12 49
In This Chapter
2
Caching
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
servers 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.
About Caching and Caching Terms 51
Default Caching Behaviors 52
A Quick Reference to Caching Topics 54
Cacheable Responses 55
Uncacheable Content (no-store and bypass-cache)
61
Cache Control Time-To-Live (TTL) 63
Honor HTTP Cache-Control:max-age and Expires
Headers 66
Scheduled Invalidation 70
Require Revalidation 72
Zero-TTL Content 73
Asynchronous Refresh (prefresh) 75
50 Akamai Technologies, Inc.
Chapter 2: Caching
Related
Resources
There are major topics not covered in this guide but in other documents. These
materials are available at the Akamai EdgeControl Management Center at
ht t ps: / / cont r ol . 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.
Edge Server Configuration Guide 5/14/12 51
About Caching and Caching Terms Confidential & 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 locationthat 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.
52 Akamai Technologies, Inc.
Chapter 2: Caching
Def ault 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 customers content, and the max-age can
be set to different durations based on the nature of the content.
No-store and
Bypass-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-Control
Cacheability 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 and
Bypass-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 origins 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 Failed
Revalidation
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 by
Default
Once 90% of the objects 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
Edge Server Configuration Guide 5/14/12 53
Default Caching Behaviors Confidential & 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 Remaining
Lifetime
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 Not
Cached
By default responses to POST requests are not cached. You can configure the Akamai
serve to cache these responses.
Output of ESI Processing
Not 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.
54 Akamai Technologies, Inc.
Chapter 2: Caching
A Quick Ref erence to Caching Topics
If You Want To Do This See This Feature Page
Basics
Set max-age on objectsusing edge server configuration or
EdgeControl response Header
Cache Control Time-To-Live (TTL) 63
Set the max-age or Expiresdata using HTTP Cache-control
or Expires
Honor HTTP Cache-Control:max-age and
ExpiresHeaders
66
M ark 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 hasexpired
Require Revalidation 72
Require IM S (If-M odified-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 (asynchronousrefresh, not waiting for a client
request to refresh objects) with other caching optionsto
increase performance and reduce latency
AsynchronousRefresh (prefresh) 75
Advanced
Limit the refresh requeststo the origin. Limiting Refresh Requeststo the Origin 83
Set a TTL on error responsesto refresh attempts Error Response Time To Live (Negative TTL) 84
Use Entity Tags Entity Tag Validation Support 80
Cache 302-Redirectsby default Cache 302 Responsesby Default 86
Cache POST responses Cache POST Responses 82
Downstream
M anage caching downstream of Akamai, including busting
cachesand handling browser issues
Downstream Caching 89
Edge Server Configuration Guide 5/14/12 55
Cacheable Responses Confidential & 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 M ultiple Choices cached yes
301 M oved Permanently cached
if no redirect chase
c
302 M oved Temporarily cached if expiryinfo
if no redirect chase
c
303 See Other *
304 Not M odified
305 Use Proxy(proxyredirect) * negatively
307 TemporaryRedirect*
Client Error 4xx
400 Bad Request
negatively(if origin)
a
no
b
401 Unauthorized
402 Payment Required *
403 Forbidden
negativelyif configured
d
404 Not Found negatively yes
405 M ethod Not Allowed * negatively yes
406 Not Acceptable *
407 ProxyAuthentication Required *
408 Request Timeout *
409 Confict *
56 Akamai Technologies, Inc.
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: pr eser ve- st al e- obj ect s
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: pr eser ve- st al e- obj ect s 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 EntityTo Large *
414 Request-URI Too Long *
415 Unsupported M edia 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 GatewayTimeout *
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 servers reason phrase to the client by
setting the metadata
edgeser vi ces: modi f y- i ncomi ng- r esponse. pass- r eason- phr ase.
Edge Server Configuration Guide 5/14/12 57
Cacheable Responses Confidential & Proprietary
Factors That
Impact
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 - cachi ng 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 or
Bypass-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.)
58 Akamai Technologies, Inc.
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 Feature
Metadata
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: negat i ve- t t l 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
Edge Server Configuration Guide 5/14/12 59
Cacheable Responses Confidential & Proprietary
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: popul ar i t y- t hr eshol d) is used, the
response is not cacheable until it reaches the required threshold.
Hash Serial and Forward
When the hash-serial-and-foward metadata <f or war d: hash- ser i al - and- f or war d>
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 That
Impact
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-obj
ects 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-store
Metadata
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-cache
Metadata
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.
60 Akamai Technologies, Inc.
Chapter 2: Caching
Chase-redirects
Metadata
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.
Edge Server Configuration Guide 5/14/12 61
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. (Its 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- Cont r ol :
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 HTTP
Response Header
You can specify no-store or bypass-cache using the Edge-control header. This
metadata element takes no argument.
For example:
Edge- Cont r ol : no- st or e
Edge- Cont r ol : bypass- cache
You can also un-set no-store or bypass-cache using an Edge-Control header with the
62 Akamai Technologies, Inc.
Chapter 2: Caching
exclamation mark (!).
Edge- Cont r ol : ! no- st or e
Edge- Cont r ol : ! bypass- cache
By Configuration
File
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.
Edge Server Configuration Guide 5/14/12 63
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 ht t ps: / / cont r ol . 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- Cont r ol :
maxage response header sent with the object by the origin server.
In the case where an objects 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
64 Akamai Technologies, Inc.
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 Developers
Guide for more information.)
By HTTP
Response
Headers
You can specify time-to-live in a response header using the Edge-Control header
cache- maxage. Examples:
Edge- cont r ol : cache- maxage=90m
Edge- cont r ol : cache- maxage=1h
Edge- cont r ol : 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- Cont r ol : 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.
Edge Server Configuration Guide 5/14/12 65
Cache Control Time-To-Live (TTL) Confidential & Proprietary
without the explicit s.
By Configuration
File
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- cont r ol : cache- maxage=90m, ! no- st or e, ! bypass- cache
Note that the directives are comma-delimited with no space characters.
66 Akamai Technologies, Inc.
Chapter 2: Caching
Honor HTTP Cache-Control:max-age and Expires
Headers
Akamai servers generally ignore HTTP Cache- Cont r ol and Expi r es 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- Cont r ol or Expi r es values to determine the
time-to-live (TTL) for the object. In addition, Akamai servers can honor
Cache- Cont r ol 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- Cont r ol : 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- Cont r ol : 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.
Technical
Details
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 pr i vat e and must - r eval i dat e directives
Precedence When Honor Cache Control and Honor Expires features are enabled, the
Cache- Cont r ol and Expi r es headers take precedence over corresponding
cacheability settings in the configuration files, but will not override TTL settings in
Edge Server Configuration Guide 5/14/12 67
Honor HTTP Cache-Control:max-age and Expires Headers Confidential & Proprietary
an ARL or the Edge- Cont r ol : 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- Cont r ol : r esponse header containing a recognized cacheability setting
(no-store, !no-store, bypass-cache, !bypass-cache, or max-age).
HTTP Cache- Cont r ol : header containing a cacheability setting (no-store,
no-cache, max-age)
HTTP Expi r es header
Customer-level edge server configuration file cache-maxage
You should also remember that no- st or e/ 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- Cont r ol : max- age=600, no- st or e
the response will not be cached, and it will evict any pre-existing response from
cache, because no- st or e is the most restrictive behavior. In the presence of a
no- st or e 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- st or e 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- st or e 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- Cont r ol and Expi r es headers completely
skips evaluation of the headers if there is an Edge- Cont r ol header that contains a
cacheability statement (no-store, bypass-cache, or max-age). Unfortunately, the code
is written such that an Edge- Cont r ol : ! bypass- cache or Edge- Cont r ol :
! no- st or e will also cause the Cache- Cont r ol and Expi r es headers to be ignored. As
a result, it is not possible to turn off cache: no- st or e or cache: bypass settings in
the configuration file through use of an Edge- Cont r ol header, and also set the
max-age with a Cache- Cont r ol header. Its necessary in this case to set the max-age
with the Edge- Cont r ol header.
Controlling
Akamai Cache
With HTTP
Headers
In the absence of other settings that would take precedence, the following is the
simple version of how Cache- Cont r ol : maxage and Expi r es headers are used:
If Honor Cache Control is on and the Akamai server receives a
Cache- Cont r ol : max- age header in the response from the origin server, it uses
that setting for the lifetime of the object. Note that Cache- Cont r ol : no- st or e
68 Akamai Technologies, Inc.
Chapter 2: Caching
and Cache- Cont r ol : no- cache are honored along with Cache- Cont r ol :
max- age.
Cache- Cont r ol : pr i vat e and Cache- Cont r ol : must - r eval i dat e 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 Expi r es header in
the response from the origin server and the expiration is in the future, the
Akamai server uses the implicit max-age (the Expi r es minus the Dat e) 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- cont r ol : no- cache=" set - cooki e, set - cooki e2"
The above setting would be interpreted as a no-cache directive.
Headers in
Responses to
Clients
In the response to clients, if the Akamai server receives a Cache- Cont r ol : max- age
header from the origin, it sends a Cache- Cont r ol : 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 (Expi r es
minus Dat e) is greater than zero, it adds an Expi r es header equal to "now + implicit
maxage" in the response to the client. (The Expi r es header is never sent with a value
less than "now.")
This behavior for Expi r es headers preserves the downstream cache busting
capabilities of the origin server (more below).
Busting All
Caches (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- Cont r ol : no- st or e, 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:
Expi r es: now
Cache- Cont r ol : max- age=0
Cache- Cont r ol : no- st or e
Pr agma: no- cache
This cache-busting behavior also applies if:
honor-cc is "on" and the Akamai server receives HTTP Cache- Cont r ol :
no- cache or Cache- Cont r ol : no- st or e headers in a response from the origin
server.
Edge Server Configuration Guide 5/14/12 69
Honor HTTP Cache-Control:max-age and Expires Headers Confidential & Proprietary
honor-expires is "on" and the Akamai server receives an Expi r es header in the
past but no Cache- Cont r ol : max- age header.
Busting
Downstream
Caches 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- Cont r ol : cache- maxage header and
Cache- Cont r ol : no- st or e and/or Expi r es headers. For example:
Edge- Cont r ol : cache- maxage=1h
Cache- Cont r ol : no- st or e
Expi r es: now
This would cause the Akamai server to cache the object for one hour, but pass the
Cache- Cont r ol : max- age and Expi r es: 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-Control
Extensions in
Internet Explorer
Internet Explorer allows a post-check and a pre-check parameter in the
Cache-Control HTTP header as specified at ht t p: / / msdn. mi cr osof t . com/
wor kshop/ aut hor / per f / per f t i ps. 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- Cont r ol 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.
70 Akamai Technologies, Inc.
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.
Edge Server Configuration Guide 5/14/12 71
Scheduled Invalidation Confidential & 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.
72 Akamai Technologies, Inc.
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.
By HTTP
Response
Headers
The response header metadata component must - r eval i dat e instructs Akamai
servers not to serve a cached object that may be stale and cannot be revalidated. For
example:
Edge- cont r ol : must - r eval i dat e
By Configuration
Files
The Integration Consultant should submit a provisioning request that includes the
basic required information. No additional information is required.
Edge Server Configuration Guide 5/14/12 73
Zero-TTL Content Confidential & 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 dynamicdoes 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 sites 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
74 Akamai Technologies, Inc.
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 HTTP
Response Header
You can specify Zero-TTL in a response header using the Edge-control header
cache- maxage. For example:
Edge- cont r ol : cache- maxage=0s
By Configuration
File
The Integration Consultant should submit a provisioning request that includes the
basic required information. No additional information is required.
Edge Server Configuration Guide 5/14/12 75
Asynchronous Refresh (prefresh) Confidential & Proprietary
Asynchronous Ref resh (pref resh)
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 objects
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.
76 Akamai Technologies, Inc.
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 With
Akamai Prefresh
When the Asynchronous Refresh feature is used, the Akamai server's refresh behavior
is modified by the additional parameter cache: pr ef r esh
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: pr ef r esh 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: pr ef r esh setting is not relevant in this case, because the time-to-live will
always have expired and the content must be refreshed synchronously.
L
a
s
t

R
e
f
r
e
s
h
Total TTL
a
k
a
m
a
i
-
p
r
e
f
r
e
s
h

no refresh asynchronous prefresh
synchronous
refresh
Edge Server Configuration Guide 5/14/12 77
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: pr ef r esh 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- Cont r ol :
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.
78 Akamai Technologies, Inc.
Chapter 2: Caching
Edge Server Configuration Guide 5/14/12 79
In This Chapter
3
Caching - Advanced
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.
Entity Tag Validation Support 80
Cache POST Responses 82
Limiting Refresh Requests to the Origin 83
Error Response Time To Live (Negative TTL) 84
Preserve Stale Object on Error Response Codes
85
Cache 302 Responses by Default 86
Quick If-Modified-Since Response 87
Serve Only If Cached 88
80 Akamai Technologies, Inc.
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.
Technical
Details
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 doesnt 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 and
If-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:
I f - None- Mat ch: " a" , " b" , " c"
For this feature to perform correctly, the origin servers ETag header should be
properly formed. This includes wrapping the value of the ETag header in quotation
marks:
ETag: 744b1614390f f 16722d6d9c8df 269a86
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.
Edge Server Configuration Guide 5/14/12 81
Entity Tag Validation Support Confidential & 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:
I f - None- Mat ch: " 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 Validators
Required
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 ETag
Behaviors
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.
82 Akamai Technologies, Inc.
Chapter 3: Caching - Advanced
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 POST
body to ESI
To send the POST request body to ESI for processing, there is an additional metadata
setting. Youll find this described in the chapter Edgecomputing under the title Process
POST Body Through DCA.
Edge Server Configuration Guide 5/14/12 83
Limiting Refresh Requests to the Origin Confidential & Proprietary
Limiting Ref resh 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.
84 Akamai Technologies, Inc.
Chapter 3: Caching - Advanced
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.
Edge Server Configuration Guide 5/14/12 85
Preserve Stale Object on Error Response Codes Confidential & Proprietary
Preserve Stale Object on Error Response Codes
The Akamai servers 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.
86 Akamai Technologies, Inc.
Chapter 3: Caching - Advanced
Cache 302 Responses by Def ault
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 doesnt include these headers in a 302 response.
Edge Server Configuration Guide 5/14/12 87
Quick If-Modified-Since Response Confidential & Proprietary
Quick If -Modif ied-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 doesnt 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.
Technical
Details
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.
88 Akamai Technologies, Inc.
Chapter 3: Caching - Advanced
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- Cont r ol : onl y- i f - 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.
Edge Server Configuration Guide 5/14/12 89
In This Chapter
4
Downstream Caching
This chapter discusses management of client
cachingat downstream proxies or at the end users
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.
Default Behaviors 90
Controls for Downstream Cacheability 91
Configuration Options - Static Content 94
Configuration Options - Dynamic Content 96
Busting Downstream Caches 97
Overriding Cache-busting Behaviors 99
90 Akamai Technologies, Inc.
Chapter 4: Downstream Caching
Def ault 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.

Edge Server Configuration Guide 5/14/12 91


Controls for Downstream Cacheability Confidential & Proprietary
Controls f or 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.
Downstream
Time-To-Live
Downstream Time-To-Live lets you choose among several options for cacheability
headers sent to the client.
Origin vs. Akamai
Control
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, its 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.
Cacheability
Headers 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,
92 Akamai Technologies, Inc.
Chapter 4: Downstream Caching
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 the
Downstream
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 servers cache and what the
origin sent
the lesser of the remaining lifetime in the Akamai servers cache and what the
origin sent. (This is the value sent when the feature is off .)
the remaining lifetime in the Akamai servers 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.
Overriding
cache-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.
ESI
Downstream
Time-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.
Edge Server Configuration Guide 5/14/12 93
Controls for Downstream Cacheability Confidential & Proprietary
Internet
Explorer
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.
94 Akamai Technologies, Inc.
Chapter 4: Downstream Caching
Conf iguration Options - Static Content
You can control the downstream cacheability of objects through either an
Edge-Control response header or through configuration file settings..
By HTTP
Response
Headers
To maintain complete control over downstream cacheability at the origin server, you
can specify downstream cacheability using the Edge-Control header
downst r eam- t t l . For example, the header might be:
Edge- Cont r ol : downst r eam- t t l =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- Cont r ol : downst r eam- t t l =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:
Expi r es: [ cur r ent t i me]
Cache- Cont r ol : max- age=0, no- st or e
Pr agma: no- cache
Although the Edge-Control header doesnt 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.
By
Conf iguration
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.
Edge Server Configuration Guide 5/14/12 95
Configuration Options - Static Content Confidential & Proprietary
responses that have received ESI processing.
96 Akamai Technologies, Inc.
Chapter 4: Downstream Caching
Conf iguration 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.
Edge Server Configuration Guide 5/14/12 97
Busting Downstream Caches Confidential & Proprietary
Busting Downstream Caches
Often its 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-cacheable
content
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:
Expi r es: [ cur r ent t i me]
Cache- Cont r ol : max- age=0
Cache- Cont r ol : no- st or e
Pr agma: 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 origins cacheability headers rather than send the headers applied by the Akamai
server.
Explicit
Cache-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.
98 Akamai Technologies, Inc.
Chapter 4: Downstream Caching
Busting All
Caches Using
HTTP Expires
and
Cache-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- Cont r ol : no- cache or Cache- Cont r ol : no- st or e headers in a
response from the origin server.
The Honor-Expires feature is used to control cacheability and the Akamai server
receives an Expi r es header in the past but no Cache- Cont r ol : max- age
header.
Busting Only
Downstream
Caches Using
Expires and
Cache-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- Cont r ol : cache- maxage
header and Cache- Cont r ol : no- st or e and/or Expi r es headers. For example:
Edge- Cont r ol : cache- maxage=1h
Cache- Cont r ol : no- st or e
Expi r es: now
This would cause the Akamai server to cache the object for one hour, but pass the
Cache- Cont r ol : max- age and Expi r es: 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.
Edge Server Configuration Guide 5/14/12 99
Overriding Cache-busting Behaviors Confidential & 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 clients 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.
100 Akamai Technologies, Inc.
Chapter 4: Downstream Caching
Edge Server Configuration Guide 5/14/12 101
In This Chapter
5
Cache Key Modif ication
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.
The Default Cache Key 102
Ignore Query String 104
Ignore Query Arguments 105
Ignore Path Components 108
Ignore Path Parameters 110
Ignore Case in Cache Key 112
Flexible Cache ID 113
102 Akamai Technologies, Inc.
Chapter 5: Cache Key Modification
The Def ault 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/ or i gi n. exampl e. com/ I ndex/ Home
/ L/ 17/ 63/ 1h/ or i gi n. exampl e. com/ I ndex/ Home
Determining
the Cache Key
You can use the request header Pr agma: akamai - x- get - t r ue- 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- Tr ue- Cache- Key: / L/ or i gi n. exampl e. com/ I ndex/ 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 (Pr agma: akamai - x- get - cache- key) indicates
Edge Server Configuration Guide 5/14/12 103
The Default Cache Key Confidential & 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/ or i gi n. exampl e. com/ I ndex/ Home
However, use of the use the Pr agma: 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.
104 Akamai Technologies, Inc.
Chapter 5: Cache Key Modification
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/
By Configuration
File
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).
Edge Server Configuration Guide 5/14/12 105
Ignore Query Arguments Confidential & 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 URLs that look like the following:
www. exampl e. com/
get f i l e. asp?f i l eI D=1234&r andomKey=a1b2&sessi onI D=32Get f i l e. 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 of
Query Arguments
By default, the Akamai server includes the query string in the cache key and makes no
modifications to it. So, two otherwise identical URLs 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=j ones&model =pr i me, the resulting cache key would be /
some. cgi ?make=j ones&model =pr i me&year =2004
106 Akamai Technologies, Inc.
Chapter 5: Cache Key Modification
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 URLs (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 URLs or Akamai ARLs that do not use a Typecode in
their structure.
Technical
Details
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.
Selecting
Arguments 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:
ht t p: / / www. exampl e. com/ af f i l i at es/
adengi ne. asp?emai l =ahusai n@akamai . com&pagei d=001&dat e=02242001&af f i l i at
ei d=2345.
If you want to use only the pagei d key=value pair (pagei d=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 (&).
Selecting
Arguments 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
Edge Server Configuration Guide 5/14/12 107
Ignore Query Arguments Confidential & Proprietary
positions two through five counted backwards from the end. Open-ended ranges are
not allowed.
For example, given the URL:
ht t p: / / www. exampl e. com/ af f i l i at es/
adengi ne. asp?emai l =ahusai n@akamai . com&pagei d=001&dat e=02242001&af f i l i at
ei d=2345.
If you want to use only the pageid key=value pair (pagei d=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 2
nd
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
108 Akamai Technologies, Inc.
Chapter 5: Cache Key Modification
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 ARLs; that is, URL's or ARLs that do not use
a Typecode in their structure.
Technical
Details
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).
Removing
Components 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:
ht t p: / / www. exampl e. com/ af f i l i at es/ emai l =ahusai n@akamai . com/ pagei d=001/
Edge Server Configuration Guide 5/14/12 109
Ignore Path Components Confidential & Proprietary
dat e=02242001/ af f i l i at ei d=2345/ adenegi ne. 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:
i gnor e pat h component s " emai l " " dat e" and " af f i l i at ei d"
i gnor e pat h component s " emai l =ah" "dat e=" and " af f i l i at edi d"
i ncl ude onl y pat h component s " af f i l i at es" " pagei d" and posi t i on 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 (/).
Removing
Components 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:
ht t p: / / www. exampl e. com/ af f i l i at es/ emai l =ahusai n@akamai . com/ pagei d=001/
dat e=02242001/ af f i l i at ei d=2345/ adenegi ne. asp
If you want to use only the "af f i l i at es" directory, the pagei d key=value pair
(pagei d=001), and the filename in the cache key, you can do so by requesting any
one of the following settings in the configuration file:
i gnor e pat h component s 2 and 4: 5
i gnor e pat h component s 3: - 2 and - 5
i ncl ude onl y pat h component s 1 3 and 6
i ncl ude onl y pat h component s 1 4 and - 6
Integration The Integration Consultant should submit a provisioning request. In addition to the
basic required information, the request should explicitly state the following:
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.
110 Akamai Technologies, Inc.
Chapter 5: Cache Key Modification
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 ARLs; that is, URL's or ARLs that do not use
a Typecode in their structure.
Technical
Details
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:
ht t p: / / www. exampl e. com/ af f i l i at es; emai l =ahusai n@akamai . com;
pagei d=001; dat e=02242001; af f i l i at ei d=2345/ adenegi ne. 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:
i gnor e pat h par amet er s " emai l " " dat e" af f i l i at ei d
i ncl ude onl y pat h par amet er " pagei d"
Integration The Integration Consultant should submit a provisioning request. In addition to the
basic required information, the request should explicitly state the following:
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
Edge Server Configuration Guide 5/14/12 111
Ignore Path Parameters Confidential & Proprietary
112 Akamai Technologies, Inc.
Chapter 5: Cache Key Modification
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. exampl e. com/ di r 1/ di r 2/ myf i l e. ht ml
www. exampl e. com/ Di r 1/ Di r 2/ MyFi l e. ht ml
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, youll 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.
Edge Server Configuration Guide 5/14/12 113
Flexible Cache ID Confidential & 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.
Technical
Details
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.
114 Akamai Technologies, Inc.
Chapter 5: Cache Key Modification
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 doesnt 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.
Special
User-Agent
Headers
Because the values of the standard HTTP User-Agent header can vary so much (there
are over 3000 possible header values), it isnt 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 " I E"
X- Akamai - UA- Ver si on: " 1" , " 2" , " 3", " 4" , " 5" , " 6" , " 7"
X- Akamai - UA- OS: " wi n95" , " wi n98" , " wi nNT" , " uni x" , or " macos"
X- Akamai - UA, ( a hyphen separ at ed l i st of t he t hr ee vi r t ual t ypes def i ned
above. For exampl e I E- 6- wi nNT. )
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 Key
Composition
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 Entries
with Cache IDs
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.
Edge Server Configuration Guide 5/14/12 115
Flexible Cache ID Confidential & Proprietary
For example, if there are separate cached objects for the following three requests:
ht t p: / / exampl e. com/ quer y. cgi ?page=i t em1
ht t p: / / exampl e. com/ quer y. cgi ?page=i t em2
ht t p: / / exampl e. com/ quer y. cgi ?page=i t em203
A request to purge any one of these items would purge all three, as they all are based
on the same base URL:
ht t p: / / exampl e. com/ quer y. cgi
Other Cache Key
Features
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.
116 Akamai Technologies, Inc.
Chapter 5: Cache Key Modification
Edge Server Configuration Guide 5/14/12 117
In This Chapter
6
Enhanced Availability
Whenever an Akamai server needs to revalidate the
freshness of objects but cannot reach the origin server
to do so, the servers 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
servers ability to determine that the origin server is
not responding.
Failover (was Advanced Default Content) 118
Custom Error Pages 123
Monitor Origin Server 125
SureRoute for Failover 127
Request Queuing 128
118 Akamai Technologies, Inc.
Chapter 6: Enhanced Availability
Failover (was Advanced Def ault Content)
By default, if the origin server doesnt respond to an Akamai servers 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 cant 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 featureMonitor Origin Serveryou 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
Edge Server Configuration Guide 5/14/12 119
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.
Technical
Details
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 Status
Codes 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
120 Akamai Technologies, Inc.
Chapter 6: Enhanced Availability
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 Akamais 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. exampl e. com
to: www. bkp. exampl e. com
the configuration file would have this setting at the global level, and the redirect
prefix would be:
ht t p: / / www. bkp. exampl e. com
A failover redirect can be used as the fallback in the case of ESI processing failures.
Recreated
Request
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.
Edge Server Configuration Guide 5/14/12 121
Failover (was Advanced Default Content) Confidential & Proprietary
For example, imagine that the original request was for
www. exampl e. com/ r et ai l / el ect r oni cs/ cat egor y. asp?l oc=513
The original request arrives with a host header for www. exampl e. com, which the
Akamai server might know to be served from or i gi n. exampl e. com. Imagine also
that the Failover feature has been enabled to recreate requests for this object with the
host header of www. bkp. exampl e. com, which is served from
or i gi n. bkp. exampl e. com.
If the Akamai server cannot reach or i gi n. 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 (or i gi n. 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.
Tiered
Distribution
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.
122 Akamai Technologies, Inc.
Chapter 6: Enhanced Availability
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
Edge Server Configuration Guide 5/14/12 123
Custom Error Pages Confidential & 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 dont 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.)
Technical
Details
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 servers 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
f r om: www. exampl e. com/ auth/ ...
t o: www. exampl e. com/ error/ ...
when the client was forbidden access to content, the configuration file would have
124 Akamai Technologies, Inc.
Chapter 6: Enhanced Availability
this setting for the auth directory, and the redirect prefix would be:
=ht t p: / / www. exampl e. com/ error
Integration The Integration Consultant should submit a provisioning request. In addition to the
basic required information, the request should explicitly state the following:
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
Edge Server Configuration Guide 5/14/12 125
Monitor Origin Server Confidential & 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.
Technical
Details
In the absence of this feature, the Akamai edge server tries the IPs 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
126 Akamai Technologies, Inc.
Chapter 6: Enhanced Availability
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.
Integration The Integration Consultant should submit a provisioning request. In addition to the
basic required information, the request should explicitly state the following:
The time interval to wait before retrying bad IPs
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
Edge Server Configuration Guide 5/14/12 127
SureRoute for Failover Confidential & Proprietary
SureRoute f or 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.
Technical
Details
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 sites
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.
128 Akamai Technologies, Inc.
Chapter 6: Enhanced Availability
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 users requests.
You can use this feature to queue Edge Logging requests to ensure delivery. However
this requires a two-level edge server configuration.
Technical
Details
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
Edge Server Configuration Guide 5/14/12 129
Request Queuing Confidential & 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 doesnt overwhelm the origin with requests when it becomes available
again.
130 Akamai Technologies, Inc.
Chapter 6: Enhanced Availability
Edge Server Configuration Guide 5/14/12 131
In This Chapter
7
Auth - Browser to Edge
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:
<mat ch: r equest . met hod val ue=" AKAMAI _TRANSLATE"
r esul t =" f al se" >
. . .
</ mat ch: r equest . met hod>
General Access Control 132
Referrer Checking 133
Block Access by Client IP 135
Centralized Authorization 136
Remote Authorization 138
Edge Authorization - Cookie-Based 141
Edge/Central Hybrid Authorization 145
Edge Authorization - URL-Based - Origin Tokens
146
Edge Authorization - URL-Based - Edge Server
Tokens 151
132 Akamai Technologies, Inc.
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.
Edge Server Configuration Guide 5/14/12 133
Referrer Checking Confidential & Proprietary
Ref errer 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.
Technical
Details
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
134 Akamai Technologies, Inc.
Chapter 7: Auth - Browser to Edge
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.
Edge Server Configuration Guide 5/14/12 135
Block Access by Client IP Confidential & 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.)
Integration The Integration Consultant should submit a provisioning request. In addition to the
basic required information, the request should explicitly state the following:
A list of client IP addresses to be blocked.
The list of the IP addresses of the Web sites origin servers
136 Akamai Technologies, Inc.
Chapter 7: Auth - Browser to Edge
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 dont
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, its
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.
Technical
Details
Centralized Authorization doesnt 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
Edge Server Configuration Guide 5/14/12 137
Centralized Authorization Confidential & 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.
Integration The Integration Consultant should submit a provisioning request. In addition to the
basic required information, the request should explicitly state the following:
The list of the IP addresses of the Web sites origin servers
138 Akamai Technologies, Inc.
Chapter 7: Auth - Browser to Edge
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 Akamais 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. cust omer . com) with the content request hostname
(for example, cont ent . cust omer . 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.
Technical
Details
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
Edge Server Configuration Guide 5/14/12 139
Remote Authorization Confidential & 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 doesnt 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 Request
Cookie
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.
Tiered
Distribution
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
doesnt read data from the client; in other words, it doesnt 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 clients 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
140 Akamai Technologies, Inc.
Chapter 7: Auth - Browser to Edge
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 Server Configuration Guide 5/14/12 141


Edge Authorization - Cookie-Based Confidential & 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 ARLs on your Web site, you will need to format these
ARLs 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.
Technical
Details
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
142 Akamai Technologies, Inc.
Chapter 7: Auth - Browser to Edge
one of the steps fails, the Akamai server responds with status code 403, Access
Denied.
Using Tiered
Distribution
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 the
Cookies
To use cookie-based authorization, the Web site sends end users an Akamai-readable
cookie. The end users 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 dont 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:
/ downl oads/ *
/ f r eewar e/ poker . exe
/ ai r pl anes/ i mages/ *
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 Server Configuration Guide 5/14/12 143
Edge Authorization - Cookie-Based Confidential & 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. Its 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:
cooki ename=i p=i pval ue~expi r es=expi r est i me~access=accesspat h1! accesspat h2~md
5=MACval ue
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( i pval ue, expi r est i me, accesspat h, sal t ) )
Note that the MAC calculation uses no separators, only the values concatenated, so
the actual calculation would be:
MAC = hex( md5( i pval ueexpi r est i meaccesspat hsal t ) )
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:
mycooki e=i p=192. 22. 22. 55~expi r es=971899742~access=/ sampl e. gi f ! /
boo. exe~md5=0f 7e53e8cf 6a382000dbdb169ae68060;
The MAC for this cookie would be calculated as:
Hex( MD5( 192. 22. 22. 55971899742/ sampl e. gi f ! / boo. exemyseed) )
Sample URL using this cookie:
ht t p: / / www. exampl e. com/ sampl e. gi f
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 Access
by 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
144 Akamai Technologies, Inc.
Chapter 7: Auth - Browser to Edge
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 Server Configuration Guide 5/14/12 145
Edge/Central Hybrid Authorization Confidential & 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.
Technical
Details
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 dont 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
146 Akamai Technologies, Inc.
Chapter 7: Auth - Browser to Edge
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:
ht t p: / / downl oad. exampl e. com/ somedi r ect or y/ somef i l e. exe
to this:
ht t p: / / downl oad. exampl e. com/ somedi r ect or y/
somef i l e. exe?__gda__=1241790837_6ef 643b29daa2c7f bc23c5d89c9ec366&f i l eEx
t =. 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 doesnt 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 Server Configuration Guide 5/14/12 147
Edge Authorization - URL-Based - Origin Tokens Confidential & Proprietary
based on historical information. Effective debugging requires a working failure case
that can be observed in real time.
Technical
Details
Before going further, lets 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.
Heres that example URL again:
ht t p: / / downl oad. exampl e. com/ somedi r ect or y/
somef i l e. exe?__gda__=1241790837_6ef 643b29daa2c7f bc23c5d89c9ec366&f i l eEx
t =. exe
In the example above, the elements relevant to authorization are:
URL path: / somedi r ect or y/ somef i l e. exe&f i l eExt =. exe
Token name (or parameter): __gda__ ( conf i gur abl e; must be 5 t o 12
char act er s i n l engt h)
Token expiration: 1241790837 ( expr essed as an epoch based on GMT)
Token value: 6ef 643b29daa2c7f bc23c5d89c9ec366
Notice that the extra query argument f i l eExt =. 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 clients IP address or the value of a session cookie is sometimes used.
Generating the
Tokens
Tokens can be added to URLs 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. Youll find them on the Akamai portal at:
https://control.akamai.com/portal/content/tools/AccessControl.jsp
148 Akamai Technologies, Inc.
Chapter 7: Auth - Browser to Edge
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 the
Auth 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 Server Configuration Guide 5/14/12 149
Edge Authorization - URL-Based - Origin Tokens Confidential & 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-Generated
Tokens
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:
t oken = hex( md5( key f r ommdt , md5( expi r at i on f r omt he t oken, URL wi t hout t he
t oken, key f r ommdt , ext r act - val ue i f speci f i ed and pr esent ) )
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. Youll find them on the Akamai portal at:
https://control.akamai.com/portal/content/tools/AccessControl.jsp
Its 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
150 Akamai Technologies, Inc.
Chapter 7: Auth - Browser to Edge
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
<excl ude- quer y>of f </ excl ude- quer y>
<gr ace- per i od>0s</ gr ace- per i od>
<hash>md5</ hash>
Edge Server Configuration Guide 5/14/12 151
Edge Authorization - URL-Based - Edge Server Tokens Confidential & 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 URLs 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:
ht t p: / / downl oad. exampl e. com/ somedi r ect or y/ somef i l e. exe
152 Akamai Technologies, Inc.
Chapter 7: Auth - Browser to Edge
to this:
ht t p: / / downl oad. exampl e. com/ somedi r ect or y/
somef i l e. exe?__gda__=1241790837_6ef 643b29daa2c7f bc23c5d89c9ec366&f i l eEx
t =. 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 doesnt 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.
Technical
Details
Before going further, lets 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.
Heres that example URL again:
ht t p: / / downl oad. exampl e. com/ somedi r ect or y/
somef i l e. exe?__gda__=1241790837_6ef 643b29daa2c7f bc23c5d89c9ec366&f i l eEx
t =. exe
In the example above, the elements relevant to authorization are:
URL path: / somedi r ect or y/ somef i l e. exe&f i l eExt =. exe
Token name (or parameter): __gda__ ( conf i gur abl e; must be 5 t o 12
char act er s i n l engt h)
Token expiration: 1241790837 ( expr essed as an epoch based on GMT)
Token value: 6ef 643b29daa2c7f bc23c5d89c9ec366
Edge Server Configuration Guide 5/14/12 153
Edge Authorization - URL-Based - Edge Server Tokens Confidential & Proprietary
Notice that the extra query argument f i l eExt =. 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 clients IP address or the value of a session cookie is sometimes used.
Generating the
Tokens on the
Akamai Server
Tokens can be added to URLs 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.
154 Akamai Technologies, Inc.
Chapter 7: Auth - Browser to Edge
Including the ESI code in URLs
Adding the necessary ESI code to URLs is fairly straightforward. You simply add the
ESI code:
<esi : var s>$gener at e_di st _aut h( original-URL ) </ esi : var s>
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:
<i mg sr c=" ht t p: / / www. exampl e. com/ exampl e. gi f ?quer yar g1=val ue1>
Then the corresponding URL reference with the ESI code would be:
<i mg sr c=" ht t p: / / www. exampl e. com/
exampl e. gi f ?quer yar g1=val ue1&<esi : var s>$gener at e_di st _aut h( ' ' ' /
exampl e. gi f ?quer yar g1=val ue1' ' ' ) </ esi : var s>>
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:
<edgecomput i ng: akamai zer . t ag- f i l t er >
<r ul e>#( ^\ w+: / / [ ^/
] +) ( [ ^\ ?] +\ ?. *) #$1$2&amp; &l t ; esi : var s&gt ; $gener at e_di st _aut h( ' ' ' $2' ' ' ) &
l t ; / esi : var s&gt ; #</ r ul e>
<f l ags></ f l ags>
<onmat ch>cont i nue</ onmat ch>
<scope>at t r </ scope>
<t ags>i mg/ sr c</ t ags>
<t ype>i ncl ude</ t ype>
</ edgecomput i ng: akamai zer . t ag- f i l t er >
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 the
Auth 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
Edge Server Configuration Guide 5/14/12 155
Edge Authorization - URL-Based - Edge Server Tokens Confidential & Proprietary
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 Caching
Issues 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 URLs 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.
156 Akamai Technologies, Inc.
Chapter 7: Auth - Browser to Edge
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
Edge Server Configuration Guide 5/14/12 157
In This Chapter
8
Auth: Edge to Origin
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:
Vi a: 1. 1 akamai . net ( ghost ) ( Akamai GHost )
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
dont 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.
Set User Agent 158
Akamai-ID Cookie 159
Signature Header Authentication 160
SSL Client Certificate Authentication 162
158 Akamai Technologies, Inc.
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 wont 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.
Edge Server Configuration Guide 5/14/12 159
Akamai-ID Cookie Confidential & 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.
Technical
Details
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.
Cooki e: mycooki e_name=mycooki e_val ue
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.
Integration The Integration Consultant should submit a provisioning request. In addition to the
basic required information, the request should explicitly state the following:
The cookie for Akamai servers to authenticate themselves to the origin server.
This would be a name=value combination.
160 Akamai Technologies, Inc.
Chapter 8: Auth: Edge to Origin
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.
Technical
Details
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- Aut h- Dat a: ver si on, Akamai - i p, cl i ent - i p, t i me, uni que- i d,
nonce
X- Akamai - G2O- Aut h- Si gn: base- 64- encoded- si gnat ur e
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 servers 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.
Edge Server Configuration Guide 5/14/12 161
Signature Header Authentication Confidential & 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.
Integration The Integration Consultant should submit a provisioning request. In addition to the
basic required information, the request should explicitly state the following:
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.
162 Akamai Technologies, Inc.
Chapter 8: Auth: Edge to Origin
SSL Client Certif icate 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.
Technical
Details
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.
Reusing
Connections
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 the
Certificate
Exchange
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
servers SSL certificate during the initial SSL handshake, not later during a
renegotiation.
Edge Server Configuration Guide 5/14/12 163
SSL Client Certificate Authentication Confidential & 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 doesnt 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 SSL
Connection
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.
164 Akamai Technologies, Inc.
Chapter 8: Auth: Edge to Origin
Edge Server Configuration Guide 5/14/12 165
In This Chapter
9
Edge Computing
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.
Edge Side Includes 166
EdgeAkamaizer 167
Process POST Body Through DCA 169
DCA Output Caching 170
166 Akamai Technologies, Inc.
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.
Technical
Details
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 ht t ps: / / cont r ol . 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 sites
content must be marked up using the ESI markup language.
By HTTP
Response
Headers
Once the Web sites 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- Cont r ol : 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- Cont r ol : dca=noop
Configuration
File
The Integration Consultant should submit a provisioning request that includes the
basic required information. No additional information is required.
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.
Edge Server Configuration Guide 5/14/12 167
EdgeAkamaizer Confidential & 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 URLs 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.
Technical
Details
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
168 Akamai Technologies, Inc.
Chapter 9: Edge Computing
Edge Akamaizer processing either through the configuration file or through HTTP
response headers.
By HTTP
Response
Headers
Once the Web sites 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- cont r ol : dca=akamai zer
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- Cont r ol : dca=noop
By Configuration
File
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.
Edge Server Configuration Guide 5/14/12 169
Process POST Body Through DCA Confidential & 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.
170 Akamai Technologies, Inc.
Chapter 9: Edge Computing
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.
Technical
Details
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-IDs through URLs 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 clients 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 the
Output 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
Edge Server Configuration Guide 5/14/12 171
DCA Output Caching Confidential & 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.
172 Akamai Technologies, Inc.
Chapter 9: Edge Computing
Edge Server Configuration Guide 5/14/12 173
In This Chapter
10
Edge Services - General
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.
Add, Pass, or Remove Headers 174
Cloning HTTP Headers 175
Forward Status Code Override 176
Client Status Code Override 177
Custom Client IP Header 178
Constructed Response 179
Support for 100 Continue Responses 181
Support for WebDAV Requests /Responses 182
EdgeScape - Content Targeting 185
174 Akamai Technologies, Inc.
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.
Edge Server Configuration Guide 5/14/12 175
Cloning HTTP Headers Confidential & 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: byt es=1024- 2047
would become
X- Range: byt es=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.
176 Akamai Technologies, Inc.
Chapter 10: Edge Services - General
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.
Technical
Details
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.
Edge Server Configuration Guide 5/14/12 177
Client Status Code Override Confidential & 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.
178 Akamai Technologies, Inc.
Chapter 10: Edge Services - General
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.
Edge Server Configuration Guide 5/14/12 179
Constructed Response Confidential & 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 doesnt 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 doesnt automatically follow
redirects.
Technical
Details
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 clients 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.
180 Akamai Technologies, Inc.
Chapter 10: Edge Services - General
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.
Edge Server Configuration Guide 5/14/12 181
Support for 100 Continue Responses Confidential & Proprietary
Support f or 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.
Technical
Details
While most client browsers (IE, Mozilla) do not use the Expect : 100- cont i nue
request header when making a POST request. The Microsoft .NET framwork
includes use of the Expect : 100- cont i nue header by default.
In addition to the standard behavior of returning the origins 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- cont i nue 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.
182 Akamai Technologies, Inc.
Chapter 10: Edge Services - General
Support f or 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.
Technical
Description
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.
Edge Server Configuration Guide 5/14/12 183
Support for WebDAV Requests /Responses Confidential & 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 Supported
Methods
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 Akamais 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..
Caching
PROPFIND
Responses
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 clients request. Akamais support eliminates this ambiguity by
always passing the OPTIONS request to the origin and the origins 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.
184 Akamai Technologies, Inc.
Chapter 10: Edge Services - General
Optionally including the Authorization header value in the cache-key for the
response. This is useful for associating the response with a particular user.
PROPFIND
Response 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.
Edge Server Configuration Guide 5/14/12 185
EdgeScape - Content Targeting Confidential & 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:
geor egi on=1, count r y_code=r eser ved, r egi on_code=r eser ved, ci t y=r eser v
ed, dma=r eser ved, pmsa=r eser ved, msa=r eser ved, ar eacode=r eser ved, count
y=r eser ved, f i ps=r eser ved, l at =r eser ved, l ong=r eser ved, t i mezone=r eser
ved, zi p=r eser ved, cont i nent =r eser ved, t hr oughput =r eser ved, net wor k=r e
ser ved, asnum=, net wor k_t ype=r eser ved
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.
Conditional
Request 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.
<mat ch: cl i ent . edgescape f i el d=" ci t y" val ue=" Pi t t sbur gh" >
<aut h: acl . deny>edgescape</ aut h: acl . deny>
</ mat ch: cl i ent . 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 with
ESI
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.
186 Akamai Technologies, Inc.
Chapter 10: Edge Services - General
Edge Server Configuration Guide 5/14/12 187
In This Chapter
11
EdgeServices - Cookie Handling
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:
ht t p: / / home. net scape. com/ newsr ef / st d/
cooki e_spec. ht ml
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
Cookies Set by the Origin 189
Generate Unique Cookies 191
Set Explicit Cookie Via Configuration File 193
Expire Browser Cookies (Beta) 194
188 Akamai Technologies, Inc.
Chapter 11: EdgeServices - Cookie Handling
supported by browsers and is not supported in the Akamai server.
Matching on
Cookies
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.
Edge Server Configuration Guide 5/14/12 189
Cookies Set by the Origin Confidential & 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 CNAMEd 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 Origin
Server 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.")
Domain
Restrictions
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 Akamais service, and thus the
cookies set by one content provider could be sent to another. This would compromise
the security of the cookies.
Rewriting
Set-Cookie
Headers
You can instruct the Akamai server to rewrite the path or the domain of a
Set - Cooki e header so that a Set - Cooki e sent from an Akamai domain in response
to a request sent to a CNAMEd hostname can be returned as a Set - Cooki e from the
same CNAMEd hostname. Thus, the client will return the cookie only to the correct
190 Akamai Technologies, Inc.
Chapter 11: EdgeServices - Cookie Handling
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 - Cooki e headers sent from the
example.edgekey.net origin and, rather than stripping the Set - Cooki e 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-Cookie
Headers in
POST
Responses
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.
Edge Server Configuration Guide 5/14/12 191
Generate Unique Cookies Confidential & 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.
Technical
Details
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.
Youll 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.
192 Akamai Technologies, Inc.
Chapter 11: EdgeServices - Cookie Handling
The Unique
Cookie 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 servers 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
Integration The Integration Consultant should submit a provisioning request. In addition to the
basic required information, the request should explicitly state the following:
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
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 (optional; if not set, the default is Akamai)
Edge Server Configuration Guide 5/14/12 193
Set Explicit Cookie Via Configuration File Confidential & Proprietary
Set Explicit Cookie Via Conf iguration 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 users 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.
Technical
Details
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.
Integration The Integration Consultant should submit a provisioning request. In addition to the
basic required information, the request should explicitly state the following:
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.
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)
194 Akamai Technologies, Inc.
Chapter 11: EdgeServices - Cookie Handling
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.
Edge Server Configuration Guide 5/14/12 195
In This Chapter
12
EdgeServices - Redirect
Handling
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.
Redirect Chasing 196
Generate Redirects Based on URL Marker 198
Generate Redirects Based On Configuration 200
196 Akamai Technologies, Inc.
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 (ht t p: / / www. exampl e. com/ i mages/ spi f f y. gi f ). They will
not chase redirects where the Location is relative (/ i mages/ spi f f y. gi f ).
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.
Technical
Details
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
Edge Server Configuration Guide 5/14/12 197
Redirect Chasing Confidential & 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 ht t ps: / /
www. exampl e. com/ a redirect to ht t p: / / www. exampl e. com/ i ndex. ht ml 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 : i ncl ude sr c or al t URL. If an esi : i ncl ude sr c or al t 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 POST
Requests
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.
198 Akamai Technologies, Inc.
Chapter 12: EdgeServices - Redirect Handling
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:
ht t p: / / www. sear chsi t e. com/ dr st / 5503/ ?ht t p: / / www. l i br ar y. yxwv. ca/
ut el / r p/ aut hor s/ byr on. ht ml
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
ht t p: / / www. sear chsi t e. com/ dr st / 5503/ ?ur l =ht t p: / /
www. l i br ar y. yxwv. ca/ ut el / r p/ aut hor s/ byr on. ht ml
would cause the Akamai server to serve a 302 Redirect where the location header was
the string that followed url=:
Locat i on: ht t p: / / www. l i br ar y. yxwv. ca/ ut el / r p/ aut hor s/ byr on. ht ml
If the URL doesnt 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.
Edge Server Configuration Guide 5/14/12 199
Generate Redirects Based on URL Marker Confidential & 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
200 Akamai Technologies, Inc.
Chapter 12: EdgeServices - Redirect Handling
Generate Redirects Based On Conf iguration
Akamai servers can redirect requests based on information in the Web sites 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.
Technical
Details
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. exampl e. com/ el ect r oni cs/
can now be redirected (through configuration files) to
www. us. exampl e. com/ r et ai l / El ect r oni cs
By default Generate Redirects will cause the eviction of an object already in cache. So,
for example, if ht t p: / / www. exampl e. com/ goodi es/ pr eci ous. j pg is in cache and
a redirect is defined in the configuration file to redirect this request to ht t p: / /
www. exampl e. com/ l ogi n. ht ml , the pr eci ous. j pg 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 dont 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.
Integration The Integration Consultant should submit a provisioning request. In addition to the
basic required information, the request should explicitly state the following:
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
Edge Server Configuration Guide 5/14/12 201
Generate Redirects Based On Configuration Confidential & Proprietary
202 Akamai Technologies, Inc.
Chapter 12: EdgeServices - Redirect Handling
Edge Server Configuration Guide 5/14/12 203
In This Chapter
13
Perf ormance
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.
Support Compressed Content 204
Last Mile Accelerator 205
Chunked Encoding 208
Prefetching 210
204 Akamai Technologies, Inc.
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.
Technical
Details
With this feature enabled, Akamai servers include the following header in requests to
the origin to advertise support for gzipped content:
Accept - Encodi ng: gzi p
If the origin server is configured to send content gzipped, it returns the content with
the headers:
Var y: Accept - Encodi ng
Cont ent - Encodi ng: gzi p
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 Var y: Accept - Encodi ng and Cont ent - Encodi ng:
gzi p headers in response to the Accept - Encodi ng: gzi p header from Akamai.
In addition, the Integration Consultant should submit a provisioning request that
includes the basic required information. No additional information is required.
Edge Server Configuration Guide 5/14/12 205
Last Mile Accelerator Confidential & 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 doesnt 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.
Technical
Details
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
206 Akamai Technologies, Inc.
Chapter 13: Performance
that do not support compressed content, Akamai servers uncompress the content on
the fly for delivery to the client in uncompressed form.
Compressing
Static (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 Var y: Accept - Encodi ng and Cont ent - Encodi ng: gzi p 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 - Encodi ng: gzi p in the request headers. Otherwise, the Akamai server
unzips the content before serving.
Compressing
Dynamic
(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 Var y: Accept - Encodi ng and Cont ent - Encodi ng:
gzi p headers. It compresses the content only if the client request included the
Accept - Encodi ng: gzi p 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.
Forcing
Uncompressed
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).
Edge Server Configuration Guide 5/14/12 207
Last Mile Accelerator Confidential & 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.
208 Akamai Technologies, Inc.
Chapter 13: Performance
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.
Technical
Details
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:
Tr ansf er - Encodi ng: 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
Cont ent - Lengt h header and a Connect i on: Keep- Al i ve 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 Cont ent - Lengt h or Connect i on:
Keep- Al i ve. 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.
Edge Server Configuration Guide 5/14/12 209
Chunked Encoding Confidential & Proprietary
client must establish a new connection for the next request.
In any case, if the content is cacheable, the Akamai server adds a Cont ent - Lengt h
header when it stores the response. When served from cache to future requests, the
response will contain a Cont ent - Lengt h header and Connect i on: Keep- Al i ve.
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:
210 Akamai Technologies, Inc.
Chapter 13: Performance
Pref etching
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 Flow
Without
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 users 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 Flow
With 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-users 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
Edge Server Configuration Guide 5/14/12 211
Prefetching Confidential & 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 t ext / ht ml . (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.
URLs 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.]
Content
Provider
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:
212 Akamai Technologies, Inc.
Chapter 13: Performance
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.
Edge Server Configuration Guide 5/14/12 213
In This Chapter
14
Forward Server
Whenever an Akamai server needs to revalidate the
freshness of objects but cannot reach the origin server
to do so, the Akamai servers 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
servers ability to determine that the origin server is
not responding.
General Forward Connection Settings 214
Host Header Modification 217
Origin Server Assignment 218
Tiered Distribution 219
SureRoute for Performance 220
Site Shield 222
214 Akamai Technologies, Inc.
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 a
Connection
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.
Edge Server Configuration Guide 5/14/12 215
General Forward Connection Settings Confidential & 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 Request
ID
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.
216 Akamai Technologies, Inc.
Chapter 14: Forward Server
Host Header Modif ication
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 :
or i gi n. exampl e. com though the client request may have been to
www. exampl e. 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 Origin
Redirects
One reason to use the clients 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 or i gi n. exampl e. comin
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. exampl e. com/ pages
and pages is a directory, the origin server may use the Host header to send a redirect
to
Locat i on: or i gi n. exampl e. 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.
Edge Server Configuration Guide 5/14/12 217
Origin Server Assignment Confidential & 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 DNS
Name
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, its 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.
218 Akamai Technologies, Inc.
Chapter 14: Forward Server
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 customers 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.
Integration The Integration Consultant should submit a provisioning request that includes the
basic required information. No additional information is required.
Edge Server Configuration Guide 5/14/12 219
SureRoute for Performance Confidential & Proprietary
SureRoute f or Perf ormance
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.
Technical
Details
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 Use
SureRoute?
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
220 Akamai Technologies, Inc.
Chapter 14: Forward Server
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
sites 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.
Edge Server Configuration Guide 5/14/12 221
Site Shield Confidential & Proprietary
Site Shield
Akamai Site Shield is the industrys 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 companys 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,
222 Akamai Technologies, Inc.
Chapter 14: Forward Server
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-Origin
Stickiness
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 IPs 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 providers 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.
Edge Server Configuration Guide 5/14/12 223
Site Shield Confidential & Proprietary
224 Akamai Technologies, Inc.
Chapter 14: Forward Server
Edge Server Configuration Guide 5/14/12 225
In This Chapter
15
Forward Path
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.
Prune or Modify Query String 226
Path Modification By Rule 227
Path Modification by Regular Expression 228
226 Akamai Technologies, Inc.
Chapter 15: Forward Path
Prune or Modif y 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 cant process or should not
see:
If the origin server doesnt 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:
/ t abl es/ di ni ng/ pr oduct sear ch. asp?pr oduct =abc&col or =bl ue
If the origin server doesnt 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:
/ t abl es/ di ni ng/ pr uduct sear ch. asp.
In the second case, the client request might contain a client-specific string for
authorization purposes
/ t abl es/ di ni ng/ pr oduct sear ch. asp?pr oduct =abc&col or =bl ue&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:
/ t abl es/ di ni ng/ pr oduct sear ch. asp?pr oduct =abc&col or =bl ue
Edge Server Configuration Guide 5/14/12 227
Path Modification By Rule Confidential & Proprietary
Path Modif ication 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:
/ di r 1/ di r 2/ f i l e. ht m
might become
/ newdi r / di r 1/ di r 2/ f i l e. ht m
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:
/ di r 1/ di r 2/ f i l e. ht m
might become
/ newdi r / di r 1/ di r 2/ l ogi n. ht m
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 ARLs, that is, ARLs
that include a typecode. Also, the cache key for the request is based on the rewritten
URL.
228 Akamai Technologies, Inc.
Chapter 15: Forward Path
Path Modif ication 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.
Edge Server Configuration Guide 5/14/12 229
In This Chapter
16
Network
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.
DNS 230
HTTP 231
ICP 232
Persistent Connections (pconns) 233
TCP Optimizations 235
Timeouts 237
Adaptive Connect Timeout (Beta) 238
Client-Side Traffic Shaping (Beta) 240
230 Akamai Technologies, Inc.
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).
Dynamically
Pre-f reshing
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.
Asynchronous
DNS Ref resh
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 DNS
Time-to-Live
This setting controls the minimum time for which the Akamai edge server will cache
a DNS resolution.
DNS Error
Time-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."
Edge Server Configuration Guide 5/14/12 231
HTTP Confidential & 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.
Unbuff ering
Responses
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.
232 Akamai Technologies, Inc.
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.
Edge Server Configuration Guide 5/14/12 233
Persistent Connections (pconns) Confidential & Proprietary
Persistent Connections (pconns)
This section describes controls for managing use of persistent connections by the
Akamai server.
Pconn
Timeouts
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 servers 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."
234 Akamai Technologies, Inc.
Chapter 16: Network
Preventing
Client 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.
Preventing
Forward 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.
Edge Server Configuration Guide 5/14/12 235
TCP Optimizations Confidential & 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 Buff er
Sizes
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.
Transport
Optimization
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
236 Akamai Technologies, Inc.
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 RFCs:
http://www.faqs.org/rfcs/rfc2001.html
http://www.faqs.org/rfcs/rfc793.html
http://www.faqs.org/rfcs/rfc1122.html
f orward-no-de
lay
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.
<net wor k: t cp. f or war d- no- del ay>of f </ net wor k: t cp. f or war d- no- del ay>
Edge Server Configuration Guide 5/14/12 237
Timeouts Confidential & 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.
238 Akamai Technologies, Inc.
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.
Technical
Details
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 wont 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 servers 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
Edge Server Configuration Guide 5/14/12 239
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.
240 Akamai Technologies, Inc.
Chapter 16: Network
Client-Side Traff ic 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.
Technical
Details
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.
Information
Header
When this feature is enabled, sending the header Pr agma: x- r at e- l i mi t i ng- dat a in a
request will return the response header X- Akamai - Rat e- Li mi t : r at e: t hr eshol d,
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.
Edge Server Configuration Guide 5/14/12 241
In This Chapter
17
Reporting
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.
Log Delivery 242
Edge Logging (Download Receipts) 245
242 Akamai Technologies, Inc.
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, ht t ps: / / cont r ol . akamai . com
Caveats You should be careful not to request more log fields than actually used.
Technical
Details
Akamai customers can choose between two log formats: Combined Log Format and
Custom Log Format. The two formats are described briefly here.
Combined Log
Format
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 Log
Format
The W3C Extended Log Format lets you to specify the fields youre 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
Edge Server Configuration Guide 5/14/12 243
Log Delivery Confidential & 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 Log
Format
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 l og- r ef er er . For example:
Edge- cont r ol : l og- r ef er er
Log User Agent: You can instruct Akamai servers to log the user agent field for a
request by using the Edge-control header l og- user - agent . For example:
Edge- cont r ol : l og- 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 Log
Format
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 l og- r ef er er . For example:
Edge- cont r ol : l og- r ef er er
Log User-Agent: You can instruct Akamai servers to log the user agent field for a
request by using the Edge-control header l og- user - agent . For example:
Edge- cont r ol : l og- 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 l og- host hdr . For example:
Edge- cont r ol : l og- host hdr
244 Akamai Technologies, Inc.
Chapter 17: Reporting
Log Cookies: You can instruct Akamai servers to log all cookies that accompany a
request by using the Edge-control header l og- cooki e. Although the metadata
component is singular, it will log all cookies with the request. For example:
Edge- cont r ol : l og- cooki e
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
l og- accept - l ang. For example:
Edge- cont r ol : l og- accept - l ang
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 Server Configuration Guide 5/14/12 245
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.
Technical
Details
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
246 Akamai Technologies, Inc.
Chapter 17: Reporting
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
Receipt
Aggregation
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 appl i cat i on/ x- www- f or m- ur l encoded. (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 Server Configuration Guide 5/14/12 247
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.
248 Akamai Technologies, Inc.
Chapter 17: Reporting
Edge Server Configuration Guide 5/14/12 249
In This Chapter
18
Security Related Features
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.
Support POST Requests 250
Support for PUT and DELETE Methods 251
Munged URL 252
Object ID Checking 253
Authenticate Object ID's 255
Use SSL Going Forward 256
250 Akamai Technologies, Inc.
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 at
the 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.
Edge Server Configuration Guide 5/14/12 251
Support for PUT and DELETE Methods Confidential & Proprietary
Support f or 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 Caching
at 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.
Integration The Integration Consultant should submit a provisioning request that includes the
basic required information. No additional information is required.
Allowing DELETE
with 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:
252 Akamai Technologies, Inc.
Chapter 18: Security Related Features
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:
ht t p: / / a9. g. akamai . net / 5/ 9/ 1440/ 000/ www. f oo. com/ i mages/
l ogo. gi f
becomes
ht t p: / / a9. g. akamai . net / 5/ 9/ 1440/ 000/ 1a1a1a940735ae1784eb197/
l ogo. gi f
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
Edge Server Configuration Guide 5/14/12 253
Object ID Checking Confidential & 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 IDs. 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.
Technical
Details
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
254 Akamai Technologies, Inc.
Chapter 18: Security Related Features
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 (and
derivatives)
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 (and
derivatives)
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.
Edge Server Configuration Guide 5/14/12 255
Authenticate Object ID's Confidential & 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.
Technical
Details
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.
Integration The Integration Consultant should submit a provisioning request. In addition to the
basic required information, the request should explicitly state the following:
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.)
256 Akamai Technologies, Inc.
Chapter 18: Security Related Features
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.
Technical
Details
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.
Edge Server Configuration Guide 5/14/12 257
In This Chapter
19
Using Variables
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.
Variables Syntax 258
Extracting Values Into Variables 260
Assigning and Transforming Variables 262
Comparing Variables 265
258 Akamai Technologies, Inc.
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:
%( VARI ABLE- NAME)
This is similar to ESIs $( VARI ABLE- 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:
<f or war d: modi f y- host - header . val ue>%( AK_HOSTHEADER) </
f or war d: modi f y- host - header . val ue>
<f or war d: or i gi n- ser ver . host >%( EXTRACTED- VALUE) <f or war d: or i gi n- ser ver . host >
Available Built-in
Variables
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.
Edge Server Configuration Guide 5/14/12 259
Variables Syntax Confidential & 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.
260 Akamai Technologies, Inc.
Chapter 19: Using Variables
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 IDs. It is the method by
which the Akamai server can insert the clients 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.
Technical
Details
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 IDs there may be one variable into which the clients 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 IDs, and is the
mechanism by which the origin server overrides an expired or invalid session ID in
the client request.
Edge Server Configuration Guide 5/14/12 261
Extracting Values Into Variables Confidential & Proprietary
Note: You cannot assign one variable to another variable. Variable values must be
constants.
262 Akamai Technologies, Inc.
Chapter 19: Using Variables
Assigning and Transf orming 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.
Tr ansf or mat i on Descr i pt i on
md5 Get t he MD5 as a hexadeci mal st r i ng of si ze 32 i n
upper case.
hmac Thi s node pr oduces a base64 encoded di gest val ue
f r omt he var i abl e val ue and key. Al gor i t hms t o
use i ncl ude: SHA1, SHA256, MD5
sha1 Cal cul at es a SHA1 hash f r omt he i nput . Not e t hat t he
comput ed hash i s i n a r aw bi nar y f or mand may
need t o be f ur t her encoded t o be usabl e.
upper Conver t t he st r i ng t o upper case.
l ower Conver t t he st r i ng t o l ower case.
t r i m Remove l eadi ng and t r ai l i ng whi t e spaces f r omi nput
ur l - encode URL encodi ng ( RFC 1738, mor e det ai l s bel ow)
ur l - decode URL decodi ng ( RFC 1738, mor e det ai l s bel ow)
ur l DecodeUni Same as ur l - decode, but al so decode uni code
encodi ng.
xml - encode XML encodi ng ( mor e det ai l s bel ow)
xml - decode XML decodi ng ( mor e det ai l s bel ow)
cssDecode Decode CSS escapi ng i n t he i nput
ht ml Ent i t yDecode Decode HTML ent i t i es pr esent i n i nput .
j sDecode Decode j avascr i pt escape sequences.
nor mal i sePat h Remove mul t i pl e sl ashes, sel f - r ef er ences and
di r ect or y back- r ef er ences.
nor mal i sePat hWi n Same as nor mal i sePat h, but f i r st conver t backsl ash
char act er s t o f or war d sl ashes.
base64encode Appl y base64 encodi ng t o a var i abl e.
base65decode Decode a base64- encoded st r i ng
hexEncode Encode i nput as hex- encoded st r i ng.
hexDecode Decode a hex- encoded st r i ng.
deci mal - t o- hex Conver t a deci mal i nt eger t o a hexadeci mal st r i ng.
hex- t o- deci mal Conver t a hexadeci mal st r i ng t o a deci mal i nt eger .
escapeSeqDecode Decode ANSI C escape sequences. I nval i d encodi ngs
ar e l ef t i n t he out put .
st r i ng- l engt h Get t he st r i ng l engt h of t he i nput .
Edge Server Configuration Guide 5/14/12 263
Assigning and Transforming Variables Confidential & Proprietary
st r i ng- i ndex Get t he posi t i on of t he f i r st occur r ence of a
subst r i ng i nsi de t he i nput st r i ng, or - 1 i f i t
i s not f ound. Thi s i s case sensi t i ve.
add i nput = i nput + val ue
subt r act i nput = i nput val ue
mul t i pl y i nput = i nput * val ue
di vi de i nput = i nput / val ue
modul o i nput = i nput %val ue
bi t wi se- and i nput = i nput & val ue
bi t wi se- or i nput = i nput | val ue
bi t wi se- xor i nput = i nput ^ val ue
bi t wi se- not i nput = ~i nput [ One' s compl ement ]
mi nus i nput = - i nput [ Two' s compl ement ]
subst r i ng Ext r act a subst r i ng.
par i t yEven7Bi t Cal cul at es even par i t y of 7- bi t dat a r epl aci ng t he
8t h bi t of each t ar get byt e wi t h t he cal cul at ed
par i t y bi t .
Par i t yOdd7Bi t Cal cul at es odd par i t y of 7- bi t dat a r epl aci ng t he
8t h bi t of each t ar get byt e wi t h t he cal cul at ed
par i t y bi t .
Par i t yZer o7Bi t Cal cul at es zer o par i t y of 7- bi t dat a r epl aci ng t he
8t h bi t of each t ar get byt e wi t h a zer o par i t y
bi t whi ch al l ows i nspect i on of even/ odd par i t y
7bi t dat a as ASCI I 7 dat a.
hash Hash t he st r i ng i nt o an i nt eger . Thi s r et ur ns t he
st r i ng r epr esent at i on of ( HASH( i nput ) %
( max- mi n+1) ) + mi n, wher e HASH i s an ar bi t r ar y
f unct i on t hat hashes a st r i ng i nt o an unsi gned
32- bi t i nt eger .
r and Gener at e a 32- bi t unsi gned r andomnumber bet ween mi n
and max.
hexr and The hexr and t r ansf or mat i on gener at es a conf i gur abl e
number of byt es of r andomdat a. Maxi mum, and
def aul t , set t i ng i s 16 byt es.
encr ypt Encr ypt t he st r i ng. The out put i s t he nonce f ol l owed
by t he base- 64 encoded encr ypt ed i nput . I n or der
t o make t he encr ypt i on non- det er mi ni st i c, a
8- byt e r andomst r i ng i s pr epended t o t he i nput
bef or e encr ypt i on.
decr ypt Decr ypt an encr ypt ed st r i ng. The f i r st 8 byt es of
t he decr ypt ed val ue ar e aut omat i cal l y del et ed.
subst i t ut e Do a r egul ar expr essi on- based subst i t ut i on ( si mi l ar
t o Per l ' s =~ s/ r egex/ r epl acement / f l ags)
The r egul ar expr essi on can use gr oupi ng.
ext r act - par am Ext r act a val ue f r oma l i st of par amet er s. Thi s i s
usef ul t o ext r act quer y par amet er s wi t hout
havi ng t o wr i t e a r egul ar expr essi on.
* I f sever al occur r ences of t he par amet er exi st ,
onl y t he f i r st one i s r et ur ned.
* I f t he par amet er i s not f ound, t he t r ansf or mat i on
f ai l s.
* The separ at or bet ween t he name and t he val ue of a
par amet er i s al ways ' =' .
Tr ansf or mat i on Descr i pt i on
264 Akamai Technologies, Inc.
Chapter 19: Using Variables
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.
r epl aceComment s Repl ace C- st yl e comment s wi t h a si ngl e space.
r epl aceNul l s Repl ace NULL byt es wi t h spaces.
r emoveNul l s Remove NULL byt es f r omi nput .
r emoveWhi t espace Remove al l whi t espace char act er s.
compr essWhi t espace Conver t whi t espace char act er s t o spaces, t hen
compr ess mul t i pl e space char act er s i nt o onl y
one.
Tr ansf or mat i on Descr i pt i on
Edge Server Configuration Guide 5/14/12 265
Comparing Variables Confidential & 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).
266 Akamai Technologies, Inc.
Chapter 19: Using Variables
Edge Server Configuration Guide 5/14/12 267
In This Chapter
20
Other Capabilities
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.
Session ID Support 268
Download Manager 271
Progressive Download Seeking 272
268 Akamai Technologies, Inc.
Chapter 20: Other Capabilities
Session ID Support
Akamai can support Web sites that use session IDs to maintain information about
user activity. For a complete description of how session IDs 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 URLs 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 doesnt include a session
ID cookie, the origin server rewrites the URLs 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 URLs 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.
Technical
Details
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 ID
Support
Requirements
The requirements for supporting use of session IDs varies depending on the
mechanism for passing the session IDs. These requirements are discussed in detail in
Edge Server Session ID Support. Following is a brief summary.
Session IDs 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.
Edge Server Configuration Guide 5/14/12 269
Session ID Support Confidential & Proprietary
Send a Set-Cookie header in a 304 Not-Modified response to an
If-Modified-Since request from Akamai.
Session IDs Only in URLs
For Akamai to support session ID's in the URL's, the content provider must be able
to:
Identify which requests potentially change the session state.
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 IDs 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 IDs in Both Cookies and URLs
For Akamai to support session ID's in both cookies and URLs, the content provider
must be able to:
Identify which requests potentially change the session state.
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- Cont r ol : 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 IDs in the URLs 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 IDs in the links (or use
270 Akamai Technologies, Inc.
Chapter 20: Other Capabilities
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).
Edge Server Configuration Guide 5/14/12 271
Download Manager Confidential & Proprietary
Download Manager
Akamais 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.
272 Akamai Technologies, Inc.
Chapter 20: Other Capabilities
Progressive Download Seeking
The Akamai server can support delivering content requested for a specific seek
location within an MP3 or FLV progressive download.
Technical
Details
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.
Edge Server Configuration Guide 5/14/12 273
In This Chapter
21
Related Services
This chapter briefly describes additional services that
involve some form of integration for use with
Akamai edge servers.
NetStorage 274
274 Akamai Technologies, Inc.
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 Akamais 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: ht t ps: / /
cont r ol . akamai . com/
Edge Server Configuration Guide 5/14/12 275
Glossary
A
Akamai server Also called edge servers. Akamai servers form a global network that provides
faster download times by allowing end users to retrieve content thats closer to the
edge of the Internet.
Akamai Resource
Locator (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.
asynchronous
request
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 users/
clients access privileges.
C
cache 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
276 EdgeSuite Configuration Guide. Confidential and Proprietary
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 customers account.
D
DCA 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.)
E
Edge, 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:
$ dat e +%s
1010705782
Glossary
EdgeSuite Configuration Guide. Confidential and Proprietary 277
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.
F
forward, forward
request
A request is "forward" if it is in the direction of the origin server.
FreeFlow typecode See typecode.
G
Acronym 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).
H
hierarchy See cache hierarchy.
Glossary
278 EdgeSuite Configuration Guide. Confidential and Proprietary
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.
I
IMS request, If-Mod-
ified-Since request
Use 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.
M
metadata Metadata, as used in reference to Akamai, is information about the content providers
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.
N
no-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).
P
personalized con-
tent
Some 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
EdgeSuite Configuration Guide. Confidential and Proprietary 279
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).
Q
query 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. exampl e. com/
get f i l e. 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.)
R
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 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
280 EdgeSuite Configuration Guide. Confidential and Proprietary
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 isnt stale.
S
session 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).
T
tiered 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
EdgeSuite Configuration Guide. Confidential and Proprietary 281
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.
V
validation The process of confirming with the origin server that the object in cache may be
served as a valid response.
W
Wfetch A Microsoft program (wfetch.exe) for issuing HTTP requests and viewing the raw
response, including the status code and response headers.
Glossary
282 EdgeSuite Configuration Guide. Confidential and Proprietary

You might also like