Aptimize Accelerator - Advanced User Guide - July 2010

Aptimize Accelerator Advanced Users Guide

Copyright © 2010 Aptimize Ltd of 56

About this Guide Aptimize is all about speed. The products in the Aptimize Accelerator family (collectively known as WAX) are designed to make the process of accelerating any website fast and simple. This guide provides deep insight into the workings of WAX and how to leverage the acceleration features it offers.

Contents 1. Introduction ......................................................................................... 4

2. About Aptimize Accelerator ................................................................. 4

Installation ............................................................................................................................................. 4

Configuration ........................................................................................................................................ 6

3. Installing the Accelerator ..................................................................... 6

Safe mode vs. Expert mode 7

Configuring the site profile 7

Verifying that WAX is working 8

Installation troubleshooting 9

4. Identifying speed bottlenecks .............................................................. 9

5. Key concepts for working with WAX .................................................. 10

Using WAX query string commands ................................................................................................... 10

The wax.config file 11

Custom rules and settings 11

Rule structure ..................................................................................................................................... 12

WAX resource naming 12

Transforming content 13

Example 1: Padding on combined images is missing ........................................................................ 13

Example 2: Bootstrapper script loads its own dependencies ............................................................. 13

Example 3 : Versioning URLs of other objects ................................................................................... 14

Transformation Tips ............................................................................................................................ 15

JavaScript debugging 15

Tracing HTTP traffic flow 15

Logging and debug trace 16

6. Getting the site as fast as possible ................................................... 17

Reading waterfall charts 17

Rule 1: Reduce the time it takes for the server to respond to a request 18

Rule 2: Reduce the number of objects being loaded by HTML pages 19



Reduce the number of StyleSheet objects ......................................................................................... 19

Reduce the number of JavaScript objects .......................................................................................... 19

Reduce the number of image requests .............................................................................................. 21

CSS background images .................................................................................................................... 21

HTML images ..................................................................................................................................... 22

Improving reuse – the groupName attribute and named resource sets ............................................. 23

Rule 3: Reduce the size of everything sent from the server 24

Rule 4: Cache everything as much as possible to speed up repeat views 25

Public proxy caching ........................................................................................................................... 25

In memory caching ............................................................................................................................. 26

Disk caching ....................................................................................................................................... 26

Accelerating external site content 26

Instructing WAX to process content from other sites ......................................................................... 26

Leveraging a Content Delivery Network ............................................................................................. 28

7. Testing the speed improvement ........................................................ 29

Stealth mode in Production 29

Testing tools ....................................................................................................................................... 30

Testing in a pre-production environment 30

8. Deployment to Production ................................................................. 30

Moving from test to production 31

Multi-server / load-balanced configuration 31

Specifying a cache path 31

Testing the cache ............................................................................................................................... 33

Set LogInfoLevel to Error 33

Set CacheMaxMemory appropriately for the size of your site 34

Move log files from default location 34

9. Troubleshooting and FAQ ................................................................. 34

My web pages or popup windows display ? characters or other strange symbols ............................ 35

SQL Reporting Services SharePoint webpart displays an error when WAX is installed .................... 35

10. Technical Reference ....................................................................... 36

Global accelerator settings 36

Logging section ................................................................................................................................... 39

Monitoring section ............................................................................................................................... 39

ResourceSets section ......................................................................................................................... 40

SearchEngineCrawlers section .......................................................................................................... 40

SpecifiedDomains section .................................................................................................................. 41

Rules section ...................................................................................................................................... 41

Transformations .................................................................................................................................. 42

Cluster section .................................................................................................................................... 45



Feature settings 46

General ............................................................................................................................................... 46

CSS optimization ................................................................................................................................ 47

shrinkCss ............................................................................................................................................ 47

combineStyleSheets ........................................................................................................................... 47

JavaScript optimization ....................................................................................................................... 47

Image optimization .............................................................................................................................. 48

Caching ............................................................................................................................................... 49

Compression ....................................................................................................................................... 49

Logging ............................................................................................................................................... 50

11. Advanced configuration scenarios ................................................... 51

Special considerations for sites running under HTTPS 51

ISAPI mode vs. HttpModule mode 51

Running WAX in proxy mode 52

WAX for Windows ............................................................................................................................... 52

WAX for Linux ..................................................................................................................................... 53

Additional steps for SSL enabled sites ............................................................................................... 53

Changing the default WAX log location 53

Configuring WAX advanced health monitoring 53

Configuring the health monitoring interface ........................................................................................ 53

1. Add trusted network clients to the list ............................................................................................. 54

2. Add the application pool user identity to the Performance Monitor Users group ........................... 54

Configuring WAX for use with ADC appliances 56



1. Introduction This guide describes the process of accelerating a website using the Aptimize Accelerator product family. It covers all steps of installing the accelerator, tuning the accelerator configuration for a sample website, and deployment and monitoring of the accelerator in a production environment. It is designed as a handbook for web developers or system administrators to leverage all the power of the Aptimize Accelerator technology to get any site as fast as possible. A sample SharePoint site will be referred to throughout the guide to provide examples of the various aspects of configuration and tuning. This is a static version of an out of the box SharePoint 2007 site that has been modified to include content and script to demonstrate all features and possible issues that may be encountered in tuning accelerator configuration settings for a site. The complete sample site is available for download from the Aptimize website once logged in: https://my.aptimize.com/downloads/file/SharePointDemo.zip.

Figure 1. Sample SharePoint 2007 website

This information is not however specific to SharePoint, since the process of accelerating any website is essentially the same – all websites are typically a combination of HTML, CSS, JavaScript, images or media objects such as animations or video and it is these objects that the Aptimize Accelerator helps tune the performance of.

2. About Aptimize Accelerator Conceptually, the Aptimize Accelerator products work by intercepting incoming requests coming from web browsers, and proxying the request to the target website. This allows all content to be inspected and/or transformed into a more optimal form before being sent to the browser client.

Installation WAX installs onto the web server(s) hosting the website, silently accelerating all responses to the user. At a high level, here’s how traffic from the user’s browser flows through the Aptimize Accelerator in a typical hosting setup:

https://my.aptimize.com/downloads/file/SharePointDemo.zip



Figure 3. WAX integration architecture The internal component architecture of WAX is described by the diagram below:

Figure 2. WAX component architecture

On the Windows platform, WAX integrates into the target website; installing as a combination of an ISAPI Filter and an HTTP handler (for IIS 6 and classic mode sites), and an HTTP module for integrated pipeline sites on IIS7+. The general process for each mode is the same:



1. WAX intercepts the incoming request 2. The rule set that should apply at the request URL is determined 3. If excluded, then the request will not be processed by WAX – otherwise, 4. WAX will retrieve the headers of the content 5. The set of accelerations to be applied is determined based on content type 6. The content is transformed or optimized according to the rule settings 7. WAX streams the accelerated response back to the client browser

Since WAX intercepts and optimizes content after it has been rendered and is just about to be sent to the client, it doesn’t matter what framework or technology your website uses. As long as it is made up of the basic components mentioned earlier – HTML, CSS, JavaScript and images – WAX will simply accelerate each response as much as possible. Since WAX works as a proxy, there are some basic requirements of the infrastructure for it to function:

1. The web server must be able to establish a connection with itself. This is typically possible without any configuration, but there may be security software that prevents this – if this occurs, the security component must be reconfigured.

2. The user identity that the application runs as must be allowed to establish a connection with the local host. Again, this is the typical configuration so should be expected to work under most circumstances.

Generally speaking, if you are able to connect to the server and open the site using a local browser then WAX will also have no problem. It’s a good idea to have a specific hostname binding on each site, and a hosts file entry for this hostname since it allows for simpler testing on the server itself. If possible, this binding should accept connections on 127.0.0.1 as well as any other network address – this guarantees no ambiguity where the IP address is a shared NLB address. This setup also makes it possible to run the performance analysis tools in WAX.

Configuration Initial configuration of the accelerator on a target site is achieved by using the supplied configuration tool (found in the Aptimize programs group). This tool provides a simple graphical user interface over the underlying settings which are contained in an XML file called wax.config that lives in the site root directory. While most settings are available through the GUI, there are a number of advanced settings that can only be accessed through the wax.config file. This guide focuses principally on the manipulation of the settings directly via the wax.config file, since this provides maximum control over the accelerator behavior.

3. Installing the Accelerator As an example process for installing and managing multiple WAX versions, it is assumed that we are installing onto the server hosting the sample SharePoint site. Basic installation of the product is simple:

1. Download the latest version of the Aptimize Website Accelerator or SharePoint Accelerator 2. Install the MSI package on the target server(s)



If you are installing onto a cluster, then you must install WAX onto each node. WAX also needs to know about all servers in the cluster – you can provide this information in the cluster section of your wax.config file (refer to the Multi-server / load-balanced configuration section for more information on this). Once the product itself is installed on the server, you must install WAX onto the target website:

1. Run the WAX configuration tool 2. Select the target site and click Install 3. Switch the accelerator to the On position

The accelerator is now enabled on the site. When you switch the accelerator On, a test will also be run against the site to verify that it is accessible and functioning as expected. This appears as a tick or cross symbol at the bottom of the status section, along with a message that identifies any problems. If you get a message stating that there is a problem, refer to the installation troubleshooting section below.

Safe mode vs. Expert mode When WAX is first installed on a site it is in Safe mode. In this configuration, WAX will apply a set of basic acceleration steps that are known to be safe for almost any website. The full list of acceleration features that are enabled in Safe mode are:

- Combine all StyleSheet references into a single file and move to the top of the page

- Shrink CSS by removing non-significant whitespace and comments

- Inline CSS background images under the size threshold as base64 data

- Shrink JavaScript by removing non-significant whitespace and comments

- Version URLs that appear in the HTML or CSS that are not otherwise optimized

- Mark all non-HTML resources as cacheable by the browser client

- Compress all text based resources using deflate encoding (or gzip if requested)

- Resample JPEG images to 85% original quality and remove metadata

- Automatically strip missing resources from pages (auto-404-elimination)

- Detect missing favicon.ico and auto-serve a cacheable blank image In most cases, you will want to enter Expert mode and tune the settings to accelerate the site beyond what is possible using the default Safe mode settings. This can be done in the Aptimize configuration tool using the Safe / Expert mode radio selector.

Configuring the site profile Clicking the orange Configure button will open the configuration UI for the site. The first thing you will see here is the ability to select a profile for the site.



An acceleration profile is a predefined set of rules that have been determined by the Aptimize engineers to be required or desired to provide an optimal acceleration outcome for a particular platform. For example, the SharePoint platform requires some custom rules to prevent some images from being combined – this is required since the URL of these images is manipulated in JavaScript, causing it to become malformed if it does not match the expected form. The SharePoint website profile also contains an additional rule to transform the contents of the /_layouts/init.js script to disable the IM presence script – without this rule, a yellow security warning bar appears in Internet Explorer prompting the user to trust an ActiveX control which is not desirable in an internet scenario. When working in expert mode, the acceleration profile should be treated as a starting point – there may be situations where you wish to override the default rules, so don’t hesitate to change them if it makes sense to do so for the site you are tuning. It is however important to understand what the consequence of changing a rule will be, so you should familiarize yourself with the default profile rules and their effects. The configuration UI contains a number of options for tuning and analyzing the performance of the site – this is covered in more detail later in this guide. For now, the next step is to verify that WAX is working as expected on the site.

Verifying that WAX is working Once WAX is installed and configured on the site, you should be able to hit it from a browser and see the page marked with the Aptimize logo in the top left corner. If you don’t see the Aptimize logo, then there are 3 likely causes:

1. The accelerator is on the Off position instead of On 2. The accelerator is running in Production Mode 3. There is a problem that is preventing the accelerator from initializing

When in development mode, clicking the Aptimize logo will show useful information about the page and what WAX did in the process of accelerating it. You can also view the source of the page and search for references to wax.axd – if there are any such links then WAX is accelerating the page. The screenshot below shows a typical view of the development mode overlay, reporting what happened for the previous page view:

The information displayed in this overlay is a report of what the accelerator did for the current page view. As such, it cannot show the result of things that did not happen this page view – e.g. if background images were reported as being inlined into the StyleSheet the first page view, on subsequent page views this would not be visible since the already optimized StyleSheet would be served from cache so no actual work was done. This view is also useful to find out which combined set a particular individual object was added to.



Installation troubleshooting There are a few broad classes of problems that may occur in installation that prevent the accelerator from functioning. Many installation problems can be diagnosed using the health check view provided by the configuration tool – this is the first place to check for possible causes of any issues. It is also useful to check the Windows application event log for any errors from ASP.NET or IIS. Any errors logged to the event log are typically integration related issues – for example, an unsupported version of the .NET Framework, or an incompatibility with another IIS module. Specific symptoms and their resolution are identified below: Symptoms:

- An error page displayed only when WAX is installed

- WAX resources are served with a 400 or 404 status

- Pages take a long time to load even though the app pool is warm Problem:

- URL rewriter or other HttpModule is attempting to handle WAX URLs Resolution:

- Exclude any URL that contains /wax.axd from URL rewriting or processing by the other HttpModule. If this is not possible or does not resolve the problem, then try switching WAX from ISAPI mode to module mode or vice versa, or as a last resort try running WAX as a proxy.

Symptoms:

- The site works when accessed locally, but not when accessed externally Problem:

- Proxy or other upstream device is blocking URLs that contain /wax.axd

- Upstream device is altering WAX URLs, causing them to become invalid Resolution:

- Allow any request for /wax.axd to pass through to the host server unmodified

4. Identifying speed bottlenecks Before you start tuning any website, it is important to understand where any speed problems lie. There is for example little value in working to reduce the DNS lookup time of an external domain if the server takes 10 seconds to generate an HTML page because the DB server is overloaded. The simplest way to determine where speed bottlenecks exist is to measure the site as it loads. Below is a table

as produced by AOL webpagetest (www.webpagetest.org):

The time to first byte of 0.883s shows that the server responded relatively quickly – it spent nearly a second generating the page, which is acceptable. If server processing to generate a dynamic resource exceeds 1 second, then it is worth running a code or database profiler to understand why this occurs – this is outside the scope of this document but there are many good resources on the internet that cover this type of tuning.

http://www.webpagetest.org/



The other stats in this table show that there is room for improvement however. For this site, it takes nearly 11 seconds before the page is fully loaded, but more worryingly the time to start render is 8 seconds – this is how long a visitor will sit looking at a blank page before it starts to show any sign of life. This page request resulted in 35 requests in total – this means that after receiving the page content, the browser had to retrieve 34 other things from the server before the page was completed loading. Each of these server requests results in additional time to load the page caused by download time and network latency. In total, this page required 738 kB of data to be retrieved from the server to render. If this page were an entry point into a site then this would be considered to be very heavy – general recommendation is that you not exceed about 300 kB total weight for an entry page. If this page was a content rich page that was accessed as a 2

nd or 3

rd click in the site, then it is within tolerance, assuming that the user already has most of the site chrome

loaded and it is only the new and valuable content that is being retrieved. There are many great tools available that help diagnose if and where any speed problems might exist. Keep the following tips in mind when picking the right tool(s) for the best analysis:

- Measuring the page load time of real users is the most meaningful statistic to capture

- Real browser measurements are better than synthetic tests

- If you can’t get real-world measurements, pick a tool that can at least simulate network latency

5. Key concepts for working with WAX There are a few key concepts that must be well understood to be able to use WAX to get a site as fast as possible.

Using WAX query string commands WAX accepts a number of commands via the URL query string. This allows you to control the behavior of the accelerator for testing purposes, or for special case handling of specific URLs. Valid commands include: ?wax=off : disables WAX acceleration for the current browser session by issuing a special cookie ?wax=on : enables WAX acceleration again if disabled by the previous command ?wax=exclude : disables WAX acceleration for just the single URL that the command appears on ?wax=print : disables HTML image combining for the page URL that the command appears on (this can be added as a suffix onto a self-referencing “Print friendly view” URL that opens in another window, and allows users to print pages that have HTML image sprites without having to enable printing of background images in their browser). ?waxtrace=key : allows a verbose trace to be captured for a single page view (refer to the logging and debug trace section for more information on this command). ?waxsize=[dimensions] : if used on an image URL, WAX will resize the image prior to sending it to the client (requires the global enableQueryStringImageResize setting to be enabled). Note: If running in stealth mode, the wax=off and wax=on commands behave differently. Please refer to the section that describes using stealth mode in production for more information on this feature.



The wax.config file All accelerator settings for a particular WAX enabled site are stored in the wax.config file that lives in the site root directory. For advanced tuning and configuration, it is important to understand how to edit this file by hand. The wax.config file structure, including all valid setting names and their values are governed by the XML Schema file located in the program directory of the WAX version you are running on the site. If you are using notepad or any other plain text editor, you must be careful to preserve the validity of the XML file. A better option is to use an XML aware editor – any XML editor that can bind a schema to the XML file will ensure that the file is always valid. As an added bonus, binding a schema to the XML file like this will typically provide auto-completion of setting names and valid values. Two recommended products for editing wax.config files with auto-completion are Microsoft Visual Studio and Altova XmlSpy. If you have Visual Studio installed, simply open the wax.config file and with the editor pane selected use the Schemas setting of the properties window to browse for the appropriate WAX schema file.

Custom rules and settings Learning how to write custom rules is an essential skill in working with WAX in expert mode. A simple type of rule might be to exclude certain content from passing through the accelerator – in a more complex scenario you may add a rule for a single JavaScript file that instructs WAX not to combine it with other script files, but to still minify, compress and cache the content. Settings define the behavior of the accelerator at a particular location. The settings defined at the default location are only applied if there is no more specific rule defined for what the accelerator should do at the specified path. Rules are evaluated in the order they appear in the list – as soon as a match to the location is found, those settings will apply. There are 2 types of settings that can be defined in the wax.config file – global accelerator settings, which can only appear as attributes on the wax:configuration element, and rule specific settings which can appear on both the wax:configuration element, or any add element in the rules section. Modifying any of the latter type of setting will cause the cache key of objects at that location to change, causing client browsers to retrieve the modified content. Rules can be thought of as overriding the default behavior – i.e. the default settings will apply at all locations, except for a specified rule path in which case those settings will apply instead. Location specific rule settings are inherited from the default global settings. The default location also accepts the use of the Action attribute, which allows a default action to be applied to all locations – for example, setting action to Exclude at the default location will cause WAX to ignore all requests if there are no location specific rules. <wax:configuration ... action=”Exclude” ...>

Note: the action attribute is shown on its own above - a real configuration file would have many other attributes already present, so you should add action in addition to these other existing attributes. To save space, this is a common format for presenting example configurations.



Rule structure Rules are composed of 3 fundamental parts:

- Path : This is the full or partial URL, or the expression to match if using a wildcard or regular expression.

- MatchType : The type of match that should be applied to the URL and the Path part above.

- Action : The action that should be performed at this location if there is a match. MatchType may be one of:

- Contains : If the URL location contains the text in Path then it will be considered to be a match.

- Wildcard : The Path expression will be matched against the URL location, with * treated as a wildcard.

- Regex : The Path is assumed to be a regular expression, matching against the URL location. Action may be one of:

- Include : The matching URL will be included for acceleration, using the settings defined at this location.

- Exclude : Any matching URL will be ignored by the accelerator (i.e. the content will be unmodified).

- Strip : Any UI element that references a matching URL will be stripped . Only elements that are visible in the server-side document such as <img>, <script> or <link> tags can be stripped.

For example, this configuration will exclude all locations by default but will selectively accelerate anything in the /pages/ directory, strip a bad CSS file (for example it returns a 400 or 404), include all image files and resample JPEG images to 70% quality but not combine PNG images, and exclude any web service request. <wax:configuration ... action=”Exclude” ...>

<rules>

<add path=”/pages/” matchType=”Contains” action=”Include” />

<add path=”dodgy.css” action=”Strip” />

<add path=”*.gif” matchType=”Contains” action=”Include” />

<add path=”*.png” matchType=”Contains” action=”Include” combineImages=”False” />

<add path=”*.jpg” matchType=”Contains” action=”Include” jpegImageQuality=”70” />

<add path=”^(.*\.(asmx|svc)((/|\?|\.)[^jJ][^sS].*)?)$” matchType=”Regex” action=”Exclude” />

</rules>

</wax:configuration>

Note: All configuration settings are case sensitive, so take care to get the capitalization correct when editing the wax.config file directly. The default matchType is assumed to be Contains, so if it is not specified then this will be the default.

WAX resource naming When WAX creates a combined resource set containing one or more objects, or when a URL is automatically versioned, it will take on an identity that is different to its original name. e.g. a resource set will be named something like: /wax.axd/cache/kjmMLxSEdXYqXt3coAasow4F.gif and an auto-versioned URL will look like this: /images/foo.jpg?wax-srv=NCbG2iqkGgpIvCP9vry3Uq22 The seemingly random mix of numbers and letters in these URLs are a unique hash value of the settings, the content and any child resources that make up a particular resource. Whenever a setting is modified, any resources for which that setting applies will automatically be recalculated – any change to the content of a resource will also cause this unique key to change.



This approach allows content changes and any change to the way the accelerator should treat the content to get to the client browser immediately.

Transforming content There are times where the underlying content of the site has errors, or is structured in such a way that it limits the optimal function of the accelerator. In this case, it is possible to apply any text based transform on the content prior to WAX attempting to accelerate it. You can add one or more transformations to any location specific rule as a child element (please refer to the Transformations section for more information on possible transformations). A tool such as the Fiddler client-side proxy is very useful when defining transformation rules, as the transformed content may be easier to see in the traffic log. WAX will also report which transformations were run for a particular page in the debug overlay view. Transform rules are a very powerful tool for fixing content on the fly – here are some common scenarios in which this feature might be used:

Example 1: Padding on combined images is missing If HTML images that have padding defined in an external CSS document are combined, they may look incorrect as combined images have their padding set to 0. In most cases, where padding is used it can be replaced by margin – using a transform rule you can easily patch a CSS file to do this. The sample SharePoint site contains a news article image that uses the padding-top attribute to move it away from the top navigation bar. This CSS style appears in the core.css file like this: .articleimage { padding-top:10px; }

Applying the following transformation rule to core.css, we can change padding to margin and the combined image will appear in the exact same position as when WAX is disabled. <add matchType="Contains" path="core.css" action="Include">

<transformations>

<replace pattern="\.articleimage\s*\{\s*padding-top:10px;\s*\}"><![CDATA[.articleimage{margin-

top:10px;}]]></replace>

</transformations>

</add>

Note: The default configuration does not enable HTML image combining, and therefore does not show this problem. You can enable image combining by setting combineImages=”All” in the wax.config file.

Example 2: Bootstrapper script loads its own dependencies Another common scenario is a script which loads its own dependencies by inserting script tags into the DOM. Tags that are inserted via JavaScript are not visible to WAX and as such cannot be combined or auto versioned. In order to be able to combine these scripts we want to manually inject them into the parent document. In the sample SharePoint site, this technique is demonstrated by the /lightbox/js/scriptaculous.js script which as it loads will in turn cause the builder.js and effects.js scripts to be loaded. This is wasteful, since it causes 2 separate HTTP requests for about another 8 kbytes worth of data, in addition to the request for the scriptaculous.js file in the first place.



The solution is to use a combination of transformations; firstly a clear transformation to zero the content of the scriptaculous.js script; and secondly a series of insertUrl transformations to manually insert the dependant script content into the bootstrapper script itself. Here is the transformation rule to do this on the sample site: <add path="scriptaculous.js" action="Include">

<transformations>

<clear />

<insert><![CDATA[

var Scriptaculous = {

Version: '1.8.1',

require: function(libraryName) {

},

REQUIRED_PROTOTYPE: '1.6.0',

load: function() {

function convertVersionString(versionString){

var r = versionString.split('.');

return parseInt(r[0])*100000 + parseInt(r[1])*1000 + parseInt(r[2]);

}

if((typeof Prototype=='undefined') ||

(typeof Element == 'undefined') ||

(typeof Element.Methods=='undefined') ||

(convertVersionString(Prototype.Version) <

convertVersionString(Scriptaculous.REQUIRED_PROTOTYPE)))

throw("script.aculo.us requires the Prototype JavaScript framework >= " +

Scriptaculous.REQUIRED_PROTOTYPE);

}

}

Scriptaculous.load();

]]></insert>

<insertUrl url="/lightbox/js/builder.js"/>

<insertUrl url="/lightbox/js/effects.js"/>

</transformations>

</add>

Since the scriptaculous script is very small, the patched version is shown here in complete form – if this were a more complex script, you could use replace transformation with a regex to remove or modify the content as required rather than a combination of clear + insert transformations.

Example 3 : Versioning URLs of other objects WAX does not currently recognize and automatically version shockwave flash objects in HTML pages that are included using the embed tag. These URLs and others that appear in script or HTML can however be versioned using the autoUrlVersion transform rule. The SharePoint sample site references the well-known infinite zoom flash animation zoomquilt.swf – assuming that this SWF may change only occasionally, but that it’s important for users to see any such changes, we want to auto version this URL and cache it for as long as possible on the client. The HTML in the page for this SWF looks like this: <EMBED src="/zoomquilt.swf" width=220 height=170 type=application/x-shockwave-flash></EMBED>



And the transform rule to version any src property of the embed tag looks like this: <add matchType="Regex" path="(.*\.aspx.*)|(.*/$)" action="Include">

<transformations>

<autoUrlVersion pattern="\<embed\s*src=["'](?<url>.*?)["']" with="<embed

src="${url}"" />

</transformations>

</add>

The autoUrlVersion transform uses the named capture called <url> in the regular expression, attempting to create a well-formed URL from it. If the URL is valid, then WAX will append a query string parameter containing the hash of the file contents – this value will change every time there is a change to the file, causing the browser to request the latest version.

Transformation Tips While many things can be achieved with transformation rules, there are some considerations that should be met when choosing to use one vs. actually fixing the underlying content issue:

- Running many transforms on non-cacheable objects is CPU intensive, so try to use transform rules on cacheable objects external to HTML pages.

- Some things cannot be fixed with a transform rule, e.g. you can never run an autoUrlVersion transform on a URL that is calculated by concatenating two variables together, since this is calculated by the browser.

Unless you consider yourself a regex master, you should also get a good regular expression evaluation tool that can show replacement test results clearly (search for regex tester on the web) – this will save your sanity!

JavaScript debugging In order to accelerate a site to the maximum extent, combining JavaScript files into as few files as possible is an important step. Some script files are sensitive to the order in which they appear in the page – others have expectations about what various files in the page are named, so any changes can confuse them. It is therefore useful to be able to read JavaScript, and in particular to understand JavaScript error messages so that you can identify what the cause of any functional problems that appear when you combine or move JavaScript objects.

Tracing HTTP traffic flow Since WAX integrates into an existing environment it is subject to the rules that govern HTTP traffic flow. For example, in many installations there will be a load-balancer or firewall that terminates an SSL connection, or presents a forms-based-authentication façade that translates user credentials into a Windows access token. It is important to be able to understand the flow of traffic between the various devices, and how WAX will change this. If the server platform is running IIS7+, you can use the in-built failed request tracing feature to diagnose many problems. This is an essential skill in diagnosing problems in general with web applications, but can also help specifically in determining why WAX isn’t working in the case of a problem: http://learn.iis.net/page.aspx/266/troubleshooting-failed-requests-using-tracing-in-iis-7/. It is also important to be able to trace the HTTP traffic on the client. For this, a client-side proxy like the Fiddler tool (http://www.fiddler2.com/) is an excellent free option. There are also many good commercial HTTP tracing

http://learn.iis.net/page.aspx/266/troubleshooting-failed-requests-using-tracing-in-iis-7/

http://www.fiddler2.com/



tools – pick something that makes it easy to see the browser specific loading behavior and timings, and which allows the raw HTTP headers and content easy to inspect. Knowing how to read HTTP request and response traffic is an important aspect of tuning any website. WAX will also log information about the request headers it receives and makes requests with, depending upon the log level used – logging is covered in the next section in detail.

Logging and debug trace WAX maintain 3 types of log files – performance, debug trace, and error logs. All log files are viewable from the configuration tool by selecting the site that you wish to view logs for, then from the File menu selecting Log Viewer. The level of detail that WAX will emit is controlled by the logInfoLevel configuration setting. If you are experiencing problems with WAX after installation, or if a particular resource is not being accelerated in the expected way, it is often useful to enable a verbose debug trace. This can be done at a global level by setting logInfoLevel to Trace, e.g. <logging logInfoLevel="Trace" />

If you are running in production, it is possible to define one or more trace keys that can be used to capture a verbose level of logging detail on demand, without capturing. For example, the following logging settings will allow the use of the special trace key called “foo” to capture a single debug trace. <logging logInfoLevel="Info" >

<trace key="foo"/>

</logging>

To capture a verbose trace, the appropriate user would be instructed to request the problematic page, appending the trace key to the query string – e.g. http://www.example.com/pages/profile.aspx?waxtrace=foo

This is typically a better option than enabling logging at a global level, particularly if the site is in active use, since a very large volume of log data can be produced. Too much data makes it hard to identify the relevant information for debugging purposes. If you are tracking down an error message that is appearing when accessing the site – particularly if immediately after installation – then the error log is the place to look for detail on the cause. When in Development Mode, warnings will also be logged and will appear in the Health Check view – these messages are not critical, but do indicate some problem that may limit the maximum possible performance of the site. For example, if a StyleSheet contains invalid CSS that WAX determines would make combining it with other StyleSheets impossible, then it will automatically be excluded. If WAX can’t process a resource then it can’t accelerate it, so this is something that is desirable to fix. Performance related problems can be diagnosed, in the first instance by using the performance log viewer – this will give some indication of where the problem might be. A problem with the target website will show up as an extended duration in PageTime, or one of the components of it: Headers or FullContent – if the problem is to do with the interpretation or acceleration of a page or resource then this will show up under Optimizer time, or one of its components – e.g. CssOptimizer or ImageOptimizer.



6. Getting the site as fast as possible Making any website fast is a matter of 4 simple rules:

1. Reduce the time it takes for the server to respond to a request 2. Reduce the number of objects being loaded by HTML pages 3. Reduce the size of everything sent from the server 4. Cache everything as much as possible to speed up repeat views

The Aptimize Accelerator product family helps you apply these 4 rules to any website quickly and without changes to the website code or content. The recommended technique is to start with the accelerator in safe mode, and then (assuming in safe mode that everything looks ok) incrementally turning features on as described below.

Reading waterfall charts The waterfall chart is one of the most useful ways of seeing the loading behavior of the site, and determining where your effort should be focused. Below is a waterfall chart generated by AOL page test for the sample SharePoint site referred to above:

Analysis of this chart and the related table shows that there is room for improvement – the chart x-axis measures load time in seconds, while the y-axis shows the objects that the browser loaded to display the page that was requested. The colors on the chart represent different activity within the browser:



Turquoise is DNS lookup time – this is the time the browser spent looking up the hostname. In this case there is only one hostname being resolved, so DNS time is insignificant. It is recommended that the number of hostnames be kept to a minimum to reduce both DNS lookup time and TCP connect time. Red represents TCP connect time – this is how long it took for the TCP connection to be established with the server. Only 2 TCP connections are being established to the server from the browser since this is Internet Explorer 7. If you see TCP connect time for every object requested, it probably means that HTTP keep-alive is turned off on the server, or an intermediary proxy server does not support keep-alive. This has a serious impact on performance, so must be fixed if you see this behavior. Green is time to first byte – this is the time it took the server to start sending data (i.e. server processing time) plus network time (i.e. the time it takes the packets to travel from server to client – also known as latency). The faster the users connection to the server, the more green you will see relative to blue – this is because a fast connection still has the same latency as a slow one, so proportionally more time is spent in the back and forth chatter. Techniques such as combining resources together to reduce the request count will have the most significant effect on this. Blue is download time – this is how long it took to download the full file data from the server. Long blue lines suggest that large files are being requested from the web server. To some extent, the latency of the connection will affect the download time since TCP acknowledgements are limited by this also. Where the browser is doing nothing other than downloading data, this is a key area to investigate since this is blocking all other activity. Techniques such as compression, image resampling, and minification of script and CSS will reduce the blue on the chart. The other important measure that is visible from this chart is the time to start render – this is how long the user sat looking at a blank page until the browser started rendering. This time is represented by the strong green line running from top to bottom – in the example above, it was over 8 seconds before the browser showed any sign of life and started laying out the page. TIP: A simple process for ensuring that the site is as fast as possible is to work your way down the stepped list of objects on the waterfall chart, determining the most appropriate acceleration to apply for each object. For example, the start of the waterfall chart might show 2 redirects and then the page loading – the ideal action for this would be to rework the site such that the redirect is not necessary. Or you may be looking further down the chart at a script that loads on the page – here you would be looking to combine all scripts together if possible, and if not then to at least compress and cache them. WAX will by default attempt to accelerate every object in the safest way possible, but by overriding these defaults it is possible to make the site load even faster.

Rule 1: Reduce the time it takes for the server to respond to a request This rule really only applies to the very first request in the waterfall graph since this is the server response to the page request. In this case, the server took around 900ms to generate the page content and start sending it. The recommended maximum for page generation is around 1 second – if the server processing time pushes out beyond about 20% of the total load time, then any front end tuning done to satisfy the other 3 rules will start to become less meaningful. To get the server processing time down, you must look at server side resources and efficiency – this could be a combination of hardware upgrades, server-side code profiling and tuning, and database query tuning. This is beyond the scope of this document, though there are many good guides in the public domain that discuss server-side tuning in detail. Note: Any server-side tuning effort can only ever affect the first line on the waterfall chart, so keep this effort balanced with front-end tuning.



Rule 2: Reduce the number of objects being loaded by HTML pages Reducing the number of objects being loaded eliminates the time that is represented by the green bars (i.e. network time) in the waterfall graph. The fewer things that load, the less request / response chatter that has to occur. For users with fast broadband connections, it is this time optimization step that will accelerate their page loading experience the most. WAX will automatically reduce the number of objects loaded in 3 categories: StyleSheets, JavaScript files, and images.

Reduce the number of StyleSheet objects Reducing the CSS StyleSheet request count is an important step in accelerating the time to start rendering in the browser – the time that a visitor will spend looking at a blank page. To achieve maximum speed for StyleSheet loading, set combineStyleSheets to All at the global level – e.g. <wax:configuration ... combineStyleSheets=”All” ... >

It is also possible to enable this setting using the configuration UI in the WAX configuration tool as shown in this screenshot. This demonstrates setting the CSS StyleSheet combination to All. Other CSS related acceleration settings are covered later in this document.

Combining StyleSheets is generally a safe and effective way of accelerating page load time. Below is a list of known possible issues and their resolution: Symptoms:

- Page layout changes when combining StyleSheets Problem:

- Inline style blocks appearing between external StyleSheet links

- One or more StyleSheets contains invalid CSS and could not be parsed Resolution:

- Move inline style blocks to the appropriate StyleSheet, or change StyleSheet combining to Consecutive to preserve the order of styles.

- Use the health check view to identify the StyleSheet containing malformed CSS, and correct it either at source or by using a transform rule.

Reduce the number of JavaScript objects Getting requests for multiple JavaScript combined is one of the trickiest acceleration steps, but is very worthwhile since JavaScript is downloaded and executed sequentially. Reducing the number of JavaScript files loaded, particularly from the <head> section of the HTML document, can dramatically reduce the time to start rendering on the browser.



To cope with the fact that executing JavaScript can have side effects, browsers will load and then execute each JavaScript file sequentially – this is known as blocking behavior, since while the browser is busy doing this, all other activity is blocked. To make the site as fast as possible, JavaScript should be combined as much as possible. If the site supports it, all script references should be moved out of the head section of the document, and as close to the bottom of the body section as can be achieved. Whether this is possible or not will depend upon how many of the following conditions are true:

1. All external scripts contain no code that executes immediately (i.e. it is a library of functions) 2. The page makes no JavaScript function calls until the script that defines the function is loaded

A common cause of problems due to a violation of condition 1 is the use of document.write() in the immediate context of an external script. This approach is often used by advertising networks, which sadly makes any effort to reduce their impact on the loading time of a site largely ineffective. Most sites will meet condition 2 as long as there is not, for example, an inline script block in the head section of the HTML page that invokes a function in one of the external scripts. While using transform rules may be used effectively to move JavaScript around the page for optimal performance, it is generally simpler and more robust to work to improve the use of script . Ensuring that all external scripts are treated as function libraries, using a document loading event to apply behavior to the UI, and only linking to external sites that understand and value speed is an important part of site performance. JavaScript Combination WAX allows close control over the way that JavaScript files are combined, either by editing wax.config directly, or via the user interface as shown below.

These settings instruct WAX to move all external scripts that is found in the head section of the document to the start of the body section. If these settings are applied to a page, any inline script blocks that appear between external scripts, or after the last external script reference will also be moved – this preserves the order in case of dependencies. With the head scripts moved to the body, the body script combination settings then apply – in this case, all scripts found in the body of the document (including those that were moved from the head section) will be combined together and placed in the BodyStart insertion point. These scripts will also be minified due to the use of the Shrink scripts setting.

If JavaScript settings are used on a location specific rule that applies to a single script file, then these instructions will override the global settings, allowing very granular control over what happens to each script. For example, you may wish to ensure a specific script was always moved to the bottom of the body section, while other scripts are combined in a consecutive fashion in case they are order dependent: <wax:configuration ... combineHeadScripts=”Consecutive” combineBodyScripts=”Consecutive” ...>

<add path=”myscript.js” action=”Include”

combineHeadScripts=”All” headScriptInsertionPoint=”BodyEnd”

combineBodyScripts=”All” bodyScriptInsertionPoint=”BodyEnd” />




This rule would cause the default rules of Consecutive combination of all scripts that appear in both head and body sections, and wherever myscript.js appears in the head or the body of the document, it should be combined with All scripts that appear at the BodyEnd position (i.e. the end of the body section). Refer to the detailed JavaScript settings description in Section 10 for the various insertion points and combination techniques. Troubleshooting JavaScript The types of problems with JavaScript fall into 2 broad categories:

1. Errors due to an external script reference having been moved in the page. If order dependent code exists between the external script and other script files or an inline script block, then this may prevent normal functioning of the site. Best practice for building JavaScript libraries is to treat them as libraries of functions, and not execute any immediate code – this allows script to be combined to the maximum extent possible. To work around poorly designed script you can instruct WAX to exclude them entirely, or set combineHeadScripts=”None” and combineBodyScripts=”None” to simply prevent combination.

2. JavaScript frameworks that dynamically load script libraries into the page. These frameworks typically look for a reference to one of the scripts that they use, or will use some sort of registration function to inject the scripts that should be loaded. Since WAX refers to combined scripts using a surrogate URL, this can confuse frameworks that behave like this. The solution in this case is to either exclude these scripts, or transform the loading code such that it understands WAX.

Reduce the number of image requests The two types of images that are commonly used on websites – CSS background images and HTML images – are accelerated differently by WAX.

CSS background images CSS background images are those that are referenced from the background property in CSS, whether in an external StyleSheet or directly in a style block within the page. For these images, WAX will convert them to base64 data – the exact acceleration behavior is different depending upon the browser:

- For IE6 and IE7, the base64 data is served in a separate file with the CSS background URL referencing this file using MHTML notation

- For all other browsers, the base64 data is embedded directly into the CSS using the data:uri notation To prevent StyleSheets from growing too large, a threshold size for background image inlining is defined and controlled by the maxCssInlineSize setting. The default of 1200 bytes is a useful value for most sites – the number of images inlined must be balanced with the size of the StyleSheet. Around 60kB is the recommended maximum compressed size for a CSS StyleSheet. This feature is controlled by the inlineCssImages setting and can be defined at the default location or any on other location specific rule: <wax:configuration ... inlineCssImages=”True” ... >

Issue: The StyleSheet is very large, even with a very low maximum size threshold. Resolution: This is typically caused by a background image that is referenced from CSS on many different selectors. To overcome this, you can define a single CSS class that contains the background property, and combine this with any element specific styles on the same element – e.g.



Change this… <style>

#foo { display:block; background-image:url(foo-bg.gif); }

</style>

<div id=”foo”>this element has a background image style</div>

…to this: <style>

#foo { display:block; }

.foo-bg { background-image:url(foo-bg.gif); }

</style>

<div id=”foo” class=”foo-bg”>this element has a background image style</div>

Wherever an element has a style that applies the foo-bg.gif image as a background, it should reference the foo-bg class.

HTML images HTML images are those images that are referenced from an <img> tag in a page. To accelerate these images, WAX will create a sprite set that contains all images of a particular format. WAX then attaches some CSS style information to the <img> tag to reference this sprite as a background image, and sets the src attribute to reference a transparent gif - /wax.axd/cache/1x1. HTML image sprites can be enabled by setting combineImages to True. This setting and can be defined at the default location or any on other location specific rule: <wax:configuration ... combineImages=”True” ... >

Like CSS and JavaScript settings, you can also control the behavior of image combination via the WAX configuration tool UI. The full list of options available for image acceleration is covered later in this document.

Possible problems that may be seen when combining HTML images include: Symptom:

- A new sprite set seems to be created every time I visit the page. Problem:

- The list of images in the page is different every time, which causes WAX to create a new sprite set every page visit.

Resolution:

- Use the groupName attribute or named resource set (see below) to control which sprite set the various image resources appear in

- Add a custom rule to include the dynamic images in an uncombined form (action=”Include”, combineImages=”None” )



Symptom:

- Images on the page are losing their padding or out of alignment on the page Problem:

- Padding is being used to space the image from its neighboring UI elements Resolution:

- Use a transform rule on the CSS to match the appropriate properties, and convert padding to margin (see the section on transform rules for an example of this)

- Add a custom rule to include the dynamic images in an uncombined form (action=”Include”, combineImages=”None”)

Symptom:

- One of my images appears much larger when WAX is enabled. Problem:

- The container that holds the image uses CSS to resize the image from its native dimensions Resolution:

- Modify the page template to include a width and height attribute on the <img> element. This lets WAX know what size the image should be displayed at, and also helps the browser calculate the page layout more quickly resulting in a faster rendering time.

- Resize the image from its native dimensions down to the size of the container in which it is used. This can be done dynamically with a custom rule in WAX: (action=”Include”, size=”20x20”)

- Add a custom rule to include this image in an uncombined form (action=”Include”, combineImages=”None”)

Improving reuse – the groupName attribute and named resource sets Out of the box, the configuration of Aptimize is tuned to accelerate individual pages. If there are a large number of common references to JavaScript, CSS or image files between pages, but page specific objects are also referenced, WAX will group all objects according to their type even if these objects already exist in another set. For most sites, this behavior will result in the fastest possible first view load time for all entry points into a site. It is however possible to instruct WAX to group common resources and reuse these sets between pages if a considerable inefficiency in the reuse of resources is identified on the particular site you are accelerating. WAX offers two solutions to this – the groupName attribute, which allows resources that appear at a particular path to be grouped aside from the other objects on the page, and be ability to create named resource sets comprised of one or more individual objects. The groupName attribute For example – most SharePoint sites will serve all chrome from the /_layouts/1033/ location, while image content typically comes from an image library. In this case, adding a rule to group images in the chrome directory and letting WAX automatically mop up any remaining content images will improve the reuse. Here is an example rule to instruct the accelerator to behave in this way: <add path=”/_layouts/1033/” action=”Include” groupName=”chrome” />

Any object that contains /_layouts/1033/ as part of the path will be grouped into a set called “chrome”, and all other objects will be grouped in an appropriately named automatic set. Objects may only be grouped according to their type and format in the case of images, and if the chrome images vary from page view to page view then this will not greatly help reuse – in this case, you should use a named resource set.



Named Resource sets A named resource set is a manually defined list of resources that are known to be commonly used together on specific pages. It is possible to create named resource sets for all object types – e.g. JavaScript ,CSS and images – and wherever an object URL is seen by WAX it will be substituted with the named resource set instead. For example, rather than using the groupName attribute it would be possible to create a named resource set for all site chrome used in the same SharePoint site. Here is a sample resource set that demonstrates this concept: <resourceSets>

<set name="CommonChrome" type="GifImageSet">

<add path=”/_layouts/images/menudark.gif" />

<add path=”/_layouts/images/titlegraphic.gif" />

<add path=”/_layouts/images/gosearch.gif" />

<add path=”/_layouts/images/whitearrow.gif" />

<add path=”/_layouts/images/recycbin.gif" />

</set>

</resourceSets>

The objects in a named resource set must be specified as an absolute or root relative URL – it should be possible to enter these URLs in a browser (prefixed with the host name if required) and have the item be successfully displayed.

Rule 3: Reduce the size of everything sent from the server WAX works in 3 ways to automatically reduce the size of content sent from the server:

- All text based objects are compressed using the deflate compression algorithm (or gzip if the browser does not support deflate)

- JavaScript and CSS files are shrunk by removing all redundant whitespace characters and comments

- Redundant image information (such as metadata) is removed, and JPEG images are resampled to 85% of their original quality

The definition of what is a compressible resource is controlled by the compressableMimeTypes attribute, the default value of which is: compressableMimeTypes=”text/html,application/xhtml+xml,text/css,text/javascript,application/x-

javascript,text/xml,application/xml,application/json,text/x-component”

If you wish to add or remove items from this list, you will need to edit the wax.config file and specify the compressableMimeTypes attribute on the top level wax:configuration element or a rule element for a more specific path. The usage and customization of this setting is covered in the Compression section. Here’s a simple example of a custom rule to enable compression for a custom file type: <add path=”.ext” action=”Include” compressableMimeTypes=”text/custom” />

TIP: There are some objects that are by default not able to be shrunk by WAX but which can improve the website speed if they are. This includes Shockwave Flash or Silverlight animations – both these formats allow developers to build large files that contain redundant content or code, rather than building controls that are targeted exactly to where they are used. For example, rather than building a 1MB flash animation that displays on the homepage of the site, but displays different content on internal pages, it would be better to build a 300kB file for the homepage, and allow another 700kB file to load for the internal pages. Optimizing this type is



resource is beyond the scope of this guide, but there are good resources on the internet that can assist in doing so if this is a bottleneck.

Rule 4: Cache everything as much as possible to speed up repeat views WAX will automatically apply cache headers to all non-HTML resources – i.e. as long as it’s not a page, then it will be cached on the browser. Exactly which resources are cached is controlled by the cacheableMimeTypes attribute – the default value (which not normally visible in wax.config) for this setting is expanded as below: cacheableMimeTypes=”text/css,text/javascript,application/x-

javascript,image/gif,image/png,image/jpeg,image/jpg,image/bmp,image/x-icon,application/x-shockwave-

flash,text/x-component”

Additional mime types can be added to this list if there are objects that are not being cached, but which it is desirable to do so. Or, if the default list of cacheable mime types includes an entry that is not desired to be cached, then it can simply be removed. This setting can apply either at the default location or on any other location specific rule, allowing a single object to be marked as uncacheable if desired. This can be achieved by specifying for that location an empty cacheableMimeTypes setting, e.g. <add path=”/bar.swf” action=”Include” cacheableMimeTypes=”” />

WAX applies different cache durations to resources depending upon how it is referenced, according to the following table:

Condition Cache for

Object is combined into a resource set 1 year

Object URL was versioned by WAX 90 days

Original object URL was requested 1 hour

The length of time that a resource is cacheable on the client for is controlled by the resourceClientCacheDuration attribute that can be applied either at a global or rule specific level – for example, this rule could be specified to only cache objects on the path /volatile/ for 60 seconds: <add path=”/volatile/” action=”Include” resourceClientCacheDuration=”60” />

This setting only applies to objects that have not been combined into a set of any kind – resource sets are always cached for 1 year on the client. URLs that have been versioned by WAX are cached by default for 90 days. This represents the minimum time that these objects will be cached – it is possible to use the resourceClientCacheDuration setting to increase the length of time however.

Public proxy caching WAX can also help leverage any intermediary caching proxy server, such as is common in corporate environments and even by internet service providers. By using the proxyCacheable attribute, WAX will emit a cache-control: public header on all or any specific resources. For example, this configuration will mark all resources as publically cacheable, except for flash animation files since they are not versioned by default: <wax:configuration ... proxyCacheable=”True” ...>

<rules>

<add path=”.swf” action=”Include” proxyCacheable=”False” />

</rules>




Marking resources as proxy cacheable can provide a significant improvement in both first view and repeat view load times for users who access a site that other users have already accessed. Care should however be taken to ensure that only resources that really should be publically cached actually are, since it is very hard to force the expiry of an item once it is in the cache of an ISP on the other side of the world.

In memory caching WAX will also cache any object that is either compressible or cacheable in memory on the server, as long as there is sufficient RAM to do so. This can dramatically reduce the load on the server where the content is being sourced from a database backend, and improve the speed at which this content can be served. Changes to objects are automatically detected by WAX, according to the global resourceRecheckInterval configuration setting. The default recheck interval is 60 seconds – this means that WAX will keep serving the original object for 60 seconds, after which it will replay the original request for that object to refresh the content. While the refresh operation is in progress, all requests for that object receive the previously cached version which allows no wait time for users. Once the refresh has completed, the new object will start to be served instead – if the content has been altered in any way, then any reference to this object either from a combined resource set or from the versioned component of a URL will be recalculated, changing the URL that the browser sees. This allows changes made on the server to be received by browser clients within minutes of them being made, but until that time the browser will always use its own locally cached version, giving maximum performance.

Disk caching Combined resource sets are stored in memory for fast serving when requested, but they are also written to disk when a cachePath is specified in the WAX configuration file. Since these combined object sets have a cost to produce, this conserves the resources of the server. It is also necessary to write combined resource sets to disk in a load balanced hosting scenario, where one server node receives a request for a page that results in a combined image set to come into existence, but another node in the load balanced cluster receives the request for that combined image set. In this case, the instance of WAX running on the second node must load the combined resource set from disk and add it to its own local memory cache before serving. More information on configuring a disk cache can be found in the section on production deployment – see Specifying a cache path.

Accelerating external site content Following the rules above will allow you to dramatically accelerate all content that is served from the origin site. It is however common for sites to link to other sites, whether it’s to display a partner logo, to include a user tracking script from the vendor of that tracking system, or in an attempt to leverage common resources that might already be in the users browser cache. With some configuration, WAX can also accelerate external site content.

Instructing WAX to process content from other sites By default, only the domain that appears in the request received from users will be eligible for acceleration by WAX. Any relative URL is always considered to be served from the same domain, but an absolute URL will be tested against the settings for inclusion. For example – if WAX receives a request for http://www.example.com/page.asp, then only objects that appear on the example.com domain will be

http://www.example.com/page.asp



accelerated – all other URLs will be ignored by WAX. This behavior is controlled by the global includeFromDomains setting: includeFromDomains supports the following values:

- ThisDomain : Any URL that is on the origin domain or any derivative of it will be accelerated

- SubDomains : Only URLs on the exact subdomain will be accelerated

- SpecifiedDomains : Only URLs that are listed in the specifiedDomains section will be accelerated

- AllDomains : Any URL from any domain will be eligible for acceleration Take care if using the AllDomains setting, since this can have unintended consequences – e.g. advertising network images and scripts are typically not able to be accelerated in any way. If you wish to accelerate content from other domains, the specifiedDomains configuration section allows you to list these in a controlled fashion: <wax:configuration ... includeFromDomains=”SpecifiedDomains” ...>

<specifiedDomains>

<add path="www.foo.com" action="Include"/>

<add path="images.bar.com" action="Include"/>

</specifiedDomains>

While a webserver cannot obviously serve content for a site that it does not host, WAX can cause this content to be served from the origin site host in one of 2 ways:

- By combining the object into a resource set, since this is served from the WAX cache

- By versioning the URL, which will rewrite it to be served from the origin domain host Serving content from the origin domain rather than a variety of domains can provide significant benefits:

- The content is likely to load significantly faster. Every distinct hostname used on a page requires additional DNS resolution time and TCP connection establishment time. You are also subject to the QOS characteristics of the external site, which for the kinds of external content that people regularly link to is often very poor. For example, links to social networking bookmark images, advertising network scripts, and partner logos are often very slow.

- The chance of some content being unavailable is greatly reduced. If a site links content from 3-4 other sites, then the chance of one or more resources being temporarily unavailable is greatly increased. With an external site that is not under your direct control you are always subject to outages of that site, or to routing issues where your origin site is accessible to the user but the external site is not.

Example X: Social networking site bookmarks The SharePoint sample site contains a section on the right hand panel just beneath the News section titled “Share this”. This is a fictional feature that allows users of the site to share the page on some major social networking sites. This functionality is implemented as a script that emits the HTML using document.write wherever it is placed in the page. While this is not good practice, it is a common technique that is used by web developers. WAX allows this situation to be overcome and these images to be combined wherever they are referenced by creating an image resource set and running a transform over the script file that inserts these images. The example configuration below also demonstrates referencing external content.



First we define the image resource set: <resourceSets>

<set name="Bookmarks" type="PngImageSet">

<add path="http://b.static.ak.fbcdn.net/images/share/facebook_share_icon.gif" name="facebook” />

<add path="http://digg.com/img/badges/16x16-digg-guy.png" name="digg" />

<add path="http://static.delicious.com/img/delicious.small.gif" name="delicious" size="16x16" />

<add path="http://cdn.stumble-upon.com/images/16x16_su_3d.gif" name="stumble" />

</set>

</resourceSets>

This resource set will be used in place of any of its individual images, but only if they appear in an HTML <img> tag. We must use a transform rule to inject the details of the combined image resource into the bookmarks.js script file as shown below: <rules>

<add matchType="Contains" path="/bookmarks.js" action="Include">

<transformations>

<clear />

<insert><![CDATA[

var html = "<h3 class='ms-standardheader ms-WPTitle'><span>Share this:</span><span>";

html += "<a style='padding:3px;' href='http://www.facebook.com'><img src='${1x1}'

style='${imageset(Bookmarks,facebook,\")}' border=0 alt='Share on Facebook' /></a>";

html += "<a style='padding:3px;' href='http://del.icio.us'><img src='${1x1}'

style='${imageset(Bookmarks,delicious,\")}' border=0 alt='Bookmark on De.licio.us' /></a>";

html += "<a style='padding:3px;' href='http://www.digg.com'><img src='${1x1}'

style='${imageset(Bookmarks,digg,\")}' border=0 alt='Digg!' /></a>";

html += "<a style='padding:3px;' href='http://www.stumble-upon.com'><img src='${1x1}'

style='${imageset(Bookmarks,stumble,\")}' border=0 alt='Review on StumbleUpon' /></a>";

html += "</span>";

document.write(html);

]]></insert>

</transformations>

</add>

</rules>

First a clear transformation is applied to clear all content before sending the bookmarks.js file content. Then, an insert transform is applied – in this example, the entire contents of the file are included in their patched form since the script file is so small. The insert transform evaluates and expands the ${imageset(SetName,ItemName,QuoteChar) expressions in the content, before sending the optimized version to the browser client. Note: Referencing external objects in a resource set does not require you to use specifiedDomains or AllDomains for the includeFromDomains setting value.

Leveraging a Content Delivery Network Using the rewriteToCdn setting you can easily leverage a CDN using WAX. If combining of resources is enabled in WAX, the CDN host must be configured to proxy the origin site since the names of these resources will be dynamic. If your CDN provider only hosts content that is uploaded manually then you cannot rewrite any combined resource URLs to be hosted on the CDN. Below is a sample configuration that rewrites the URL of all non-page resources to be hosted by the CDN at cdn.example.com, including combined resource sets: <wax:configuration ... rewriteToCdn=”cdn.example.com” ...>

If your CDN host does not proxy the origin server then you would need to add a rule to prevent combined resources from being rewritten, such as:



<wax:configuration ... rewriteToCdn=”cdn.example.com” ...>

<rules>

<add path=”/wax.axd/cache” action=”Include” rewriteToCdn=”None” />

</rules>


WAX will automatically use the scheme of the incoming request when accessing a CDN host, but it is possible to specify the scheme and virtual path in the rewriteToCdn setting if required. This allows the scenario of switching all traffic up to SSL if the target website is reverse proxied through another device that terminates the SSL connection. For example: <wax:configuration ... rewriteToCdn=”https://cdn.example.com/foo/” ...>

It also allows switching all static content down to HTTP if your user audience can be trained to accept the mixed mode content warning – this can have a dramatic positive effect on performance due to the cacheability of plain HTTP URLs. Domain sharding and download parallelism It is possible to use the rewriteToCdn feature of WAX to perform domain sharding, allowing you to relocate some resource URLs to a second hostname that is in fact hosted on the same origin server by the same website. For example, if your current website is called www.example.com, your webserver will have a binding to accept requests for this hostname – using domain sharding you would add a second binding to this site called images.example.com, or cdn.example.com, or any fictional domain name, and then register this name in DNS. Here’s a sample configuration that would rewrite the URL of all images to images.example.com: <add path=”(.gif|.jpg|.png)” action=”Include” rewriteToCdn=”images.example.com” />

While techniques that attempt to make browsers download more resources in parallel such as domain sharding can work under some conditions, they can in many cases cause worse performance so it is important to measure the effect of doing this. Note: WAX can only rewrite URLs that appear in the content as rendered by the server – i.e. URLs that are evaluated by JavaScript cannot be changed automatically. It is however possible to use an autoUrlVersion transform or a simple text based transform on script content to rewrite this type of link to a different host.

7. Testing the speed improvement Verifying that any tuning efforts are actually improving the performance of the site is an important part of the process, and WAX makes it easy to test before and after measurements. The simplest way to test the speed improvement is to deploy straight to production and start measuring there while you tweak the acceleration rules. This allows realistic measurements to be taken, from real user activity.

Stealth mode in Production It is possible to enter Production mode in conjunction with stealth mode, allowing WAX to be installed in a production environment without having any effect unless it receives specific commands via the URL query string. Here’s what the global accelerator configuration settings would look like to enable this: <wax:configuration ... runMode=”Production” stealthMode=”True” ...>

http://www.example.com/



In this mode, all incoming requests for pages and objects will be ignored by WAX, allowing them to be served in their original form. However, if the request contains ?wax=on as part of the query string then WAX will issue a cookie that represents explicit instruction to accelerate all requests for this browser session. The user is then redirected back to the same location, and when WAX sees the enabling cookie on the incoming requests it will intercept and accelerate them according to the rules and settings defined in the configuration file. This allows simple use of real-world testing tools to verify performance gains – by specifying ?wax=on at the end of the URL submitted for testing, WAX can be instructed to accelerate this single page request. Comparing vs. the original result, you simply need to deduct the time for the cookie issuing redirect for an accurate measurement. Note: Prior to entering production mode, you should follow the steps outlined in the Deployment to Production section of this document.

Testing tools There are many great tools for verifying the speed of a website. The most useful tests are those that measure loading speed using a real browser, rather than a synthetic benchmark. These tools fall into 2 broad categories:

- Those that simulate user activity, but test from a variety of locations

- Those that integrate into the site and measure actual user load times AOL webpagetest (http://webpagetest.org) is a great example of the first type of test tool and is free to use. As long as the site is publically accessible then this is a simple and effective option, that gives you a nice waterfall chart to work from or present in a before / after view to other stakeholders.

Testing in a pre-production environment While stealth mode is the simplest way of getting realistic speed measurements, it is sometimes desirable to coordinate the release of WAX as a part of an application with which it has passed through quality assurance. In this case, testing that the benefit is present requires a different approach. If you have the technical expertise, AOL webpagetest can be installed in a virtual machine or on a spare physical box in an internal test environment. This then allows you to get the same reports you would from a site that is publically accessible, but network conditions must be simulated to provide insight into the expected performance for end-users. Under simulated network conditions, use an RTT (round-trip-time) of 70ms and a connection speed of 2Mbps, and for international visitors assume an RTT of 250ms and a connection speed of 1Mbps. From many test results, using these numbers provides a reliable indicator of real world performance. It is also possible to get commercial software or hardware network simulation tools – if you want to be very scientific about your performance testing, this might be an investment you wish to make. Look for a simulator that offers scripting and / or remote control since this allows you to build a simple regression suite around the performance of future site releases. The testing software should also be able to simulate a variety of user agents, request and validate dependant object requests, and be able to verify the presence of text in responses.

8. Deployment to Production Once configured correctly, the Website Accelerator is designed to run continuously in a production environment without intervention. In summary form, the key things to ensure when moving to production are:

- Install the Website Accelerator + an appropriate license on each server and site required

http://webpagetest.org/



- Import the configuration from a test environment, or customize the config in place

- Specify an on-disk cache path in the wax.config file (and any load balanced node settings)

- Set run-mode to Production in the WAX Configuration tool to hide the Aptimize logo

- Ensure that the on-disk site content and wax.config are identical on all servers in a cluster Below are the recommendations in detail for configuring the Website Accelerator for production hosting.

Moving from test to production It is assumed that the typical installation involves the process of testing the set of optimizations chosen in a development, test or other pre-production environment. It is also assumed that the move to production will be done either in an outage window, or server by server by removing each machine in turn from a cluster. When the settings are configured as desired in the test environment and you are ready to move to production, you can choose Save Config from the File menu in the Website Accelerator Config tool. Choose the location and name to save the file as, and then move this file to somewhere accessible from your production hosting environment. On the production web server, install WAX if you have not already done so. From the start menu, find the Aptimize programs group and run the Configuration tool. Select the correct website from the list on the left and then select Load Configuration from the File menu. Once loaded, you should click the Configure button, and then from the Run Mode tab switch from Development to Production. This will hide the Aptimize logo that appears in the top left of every page, and ensure that only important errors are logged to the event log. To do this you must have a valid license installed, which can be achieved by either clicking Install License if you already have a license file, or by clicking Get License. If you have saved the license file for the server to disk, you can also simply double-click the file and WAX will allow you to select the site to install it to.

Multi-server / load-balanced configuration When running on a load-balanced site, the Website Accelerator must be installed on each server, and on each site that it is to run on. The configuration file for the site must also be present on each server, along with the appropriate license. Licenses can be installed on each server by repeating the process for each machine as above, or by copying the license files directly into the site root directory and recycling the application pool for the site. Once the Website Accelerator is installed on a server and site, it is possible to synchronize the wax.config configuration file using the WAX Configuration Tool – from the Options menu, select Cluster Manager.

Specifying a cache path To allow the Website Accelerator cache to survive the IIS worker process being recycled, or to run in a load-balanced configuration, an on-disk cache path must be specified. There are 3 options for using a disk cache:



Isolated local cache This mode is suitable for single server installations, or load balanced environments where server affinity can be assured. Any local disk path can be specified in the cachePath attribute of the wax.config file, and the Website Accelerator will write it's resources to this location. The user identity of the application pool the site runs as must be granted read/write/modify permissions to this directory.

<wax:configuration ... cachePath="C:\WaxCache" ...>

Shared remote cache This mode is appropriate for single or load balanced environments, where cache redundancy is not essential (e.g. where you have a single database server, and web server nodes exist only for performance rather than redundancy). Any UNC based path can be used, as long as the user identity of the application pool as read/write/modify permissions to the remote file system and the remote share.

<wax:configuration ... cachePath="\\192.168.0.15\WaxCache" ...>

Replicated local cache This mode suits a cluster where redundancy is important. Each web server node must be configured with a local cache, into which resources are replicated from other nodes in the cluster as required. The example below shows a configuration where all nodes use a path called C:\WaxCache\SiteX to store their local copy of cached resources, and the cluster definition that allows the Website Accelerator to find remote nodes and replicate cache content as required. <wax:configuration cachePath="C:\WaxCache\SiteX">

<cluster cacheMode="Replicated" networkPath="WaxCache\SiteX" >

<node hostName="Foo" />

<node hostName="Bar" />

</cluster>


Note: On the Linux platform, this function is handled by the Apache module so the networkPath attribute is not required. The function of each of these settings is as follows: cacheMode: May be "Shared" or "Replicated". When the cluster element is not present, Shared is assumed. networkPath: This is the share name plus any child path beneath the share (Windows only). The remote server name / IP address should not be included in this setting as this is combined with the hostName of the node. hostName: Specifies the DNS name, either short or fully qualified, of each host node in the cluster. This name will be used to communicate with the WAX module, or combined with networkPath to form the full share path to find remote resources. zone: (Optional) Defines the zone that a node lives in. Any host will escalate a cache lookup to nodes in the same zone first before looking at nodes in other zones. On the Windows platform, the share identified by network path must exist on all nodes in the cluster, with the application pool user identity being granted read permission on the share (i.e. no remote write permission is required).



The local on-disk cache path must have read/write/modify permission granted to the user that the web application is running as.

Testing the cache The WAX configuration tool provides the ability to manage and test the cache settings, whatever cache mode you have selected. This feature can be accessed from the Options menu -> Cluster Manager.

The More details link provides detailed information about the cause of any problems. You should always run the Verify Cluster step whenever you add or remove a node from the cluster. Nodes that are taken out of load-balancing rotation for servicing or due to failure should be removed from the list prior to being made unavailable. This ensures that WAX will not attempt to communicate with these nodes while they are out of service. If performing a new install, it is possible to run this test with WAX switched Off – this allows you to verify that the configuration of each server is correct before switching WAX on and starting to accelerate requests.

Set LogInfoLevel to Error To ensure that the minimum of noise from the Website Accelerator in the event log, LogInfoLevel should be set to Error when running in production. At this level, only initialization info events and errors are reported. Events that are reported as errors in the logs should be investigated, as they could be causing a disruption to service for some users. Note: Error is the default value for logInfoLevel when in Production mode, so if the logInfoLevel attribute is not specified this will be assumed. In addition to being logged to the internal Aptimize log files, errors are also written to the Windows Application event log. Any errors logged here will appear from the event source “WAX” – for production site monitoring, you can use this event source to forward these messages specifically to an operations team member who understands how to respond to the error. Due to unexpected circumstances, an error may sometimes be reported while appearing to have no effect on the behavior of the system – if a false alarm like this occurs, you can silence the logs for this specific error code. Please refer to the Logging section of this document for information on how to use the suppressedErrorCodes setting. In general, only repetition of errors are a cause of alarm – an isolated error is not likely to cause any widespread harm. For example, if you see many WAXERR_2007 errors in the logs it is likely that the disk cache is invalid for some reason, or that a server in the cluster is down. Refer to the Configuring WAX advanced health monitoring section for more information on how to verify the health of the cluster.



Set CacheMaxMemory appropriately for the size of your site It is recommended that you set cacheMaxMemory to approximately 10 times the size of the content that is cached to allow for different browser versions and compression schemes. An easy way to determine this is to clear the in memory and on disk caches (delete the files from disk and recycle the worker process) and then browse to a representative page of your site. Note the total size of all files in the disk cache, then multiply that number by the estimated number of page templates in your site and then by 10. It is not necessary to retain all resources in memory cache all the time, but frequently accessed resources should ideally not be expired due to memory constraints. <wax:configuration ... cacheMaxMemory="200" ...>

The default value of 100MB is typically sufficient for most sites, but if you notice a lot of cache thrashing in the WAX monitoring statistics then try increasing this number. The cache eviction rate should not typically exceed more than a few hundred objects per minute. More information about monitoring the internal WAX performance counters is available in the section on configuring WAX advanced health monitoring.

Move log files from default location If your servers use a common location for logs that is on a separate hard disk or partition from the system files, then you can tell WAX where to store it’s log files: <wax:configuration ... logFilePath="e:\logs\WAX\example.com" ...>

WAX automatically cleans up log files when they exceed the default maximum number of hours to be kept, but if your site is very busy then these log files may be many megabytes. Under normal conditions, as long as your system drive has plenty of space then the default location is fine to store these files – if you plan to run a global debug trace in production under load, then you probably want to move your logs first as this can produce large amounts of trace data. The duration that log files will be kept for can be controlled by the settings in the logging section.

9. Troubleshooting and FAQ Troubleshooting WAX is a process of elimination – you must first determine what type of problem is occurring. All problems will be one of 4 major types: Error accessing every page, or blank content – This type of problem is typically an interaction between another device between the user and the web server, another server product, or the OS itself. Look in the WAX health check, the WAX logs and Windows application event log for any error messages. If there are no messages or they provide no further insight, try accessing the accelerated site directly on the server – if this works, then the problem is with an upstream device. Analyzing the HTTP traffic between these 2 parties will typically show the cause of the problem. Pages show the WAX logo, but content fails to be served – This type of problem is normally an issue with other HttpModules on the web site interfering with the function of WAX – e.g. a URL rewriter component that modifies WAX resource URLs, or a firewall that inspects the requests not allowing WAX accelerated URLs to pass through. The WAX logs or a HTTP traffic trace between the browser and the server normally shows this up – ensure each object is being returned with an HTTP 200 status, and drill down to the cause if not. Acceleration is working, but there is a layout problem – This is normally StyleSheet or HTML image related related; check the sections related to these types of resources: Reduce the number of StyleSheet objects and



HTML images. This problem typically requires the use of custom rules to work around whatever technique is causing WAX to optimize the content incorrectly. Acceleration is working, but there is a script error – This type of problem is covered in more detail in the Troubleshooting JavaScript section. The resolution is typically using custom rules to exclude, uncombine, or transform the script content to make it conform with recommended practice. Specific guidance for known issues are covered in the section below:

My web pages or popup windows display ? characters or other strange symbols When viewing web pages on the site, or when popup dialogs are displayed you may see question mark characters (?) or other symbols instead of text. This is more likely to occur if your website uses a non-western language character set, and may affect site visitors whose browser uses a different default characters set to the language used on the website even without WAX installed. Problem:

- The website uses a character set other than ISO8859-1 or UTF-8, but the web server does not include the charset parameter on the content-encoding header to indicate what the language character set is.

Resolution:

- Configure your web server or web application to emit the correct character set on the response headers. This can be done in the web.config of IIS based applications.

- Use the global defaultCharset setting in the WAX configuration file to define the charset that should be assumed for all content of the website.

SQL Reporting Services SharePoint webpart displays an error when WAX is installed When viewing a page with the Reporting Services SharePoint webpart displaying a report, an error message is displayed stating “execution [random_numbers] not found”. The error remains even after switching WAX off. Problem:

- Reporting Services uses a URL reservation within http.sys to provide access to the report data, but this conflicts with the Aptimize ISAPI filter.

Resolution:

- Uninstall WAX from the target site, and install in Proxy mode instead (see Running WAX in proxy mode for more information).



10. Technical Reference This section contains detailed technical reference information about the Aptimize Accelerator product. Each feature is described along with the settings that influence its behavior and examples of where the feature may be used. Some settings are required to have a value specified in the config file, while others are optional – this is expressed for each setting in square brackets next to the setting name. Setting names and their values are case sensitive, so care should be taken when editing the wax.config file by hand to ensure that the correct case is used.

Global accelerator settings WAX has many configuration settings that apply at a global level and affect the basic behavior of the accelerator. These settings may only be used on the top level wax:configuration element: enabled [required]

True - WAX optimization is enabled False - WAX optimization is disabled

runMode [required]

Development - Instructs the Website Accelerator to provide verbose message logging, and to display optimizer info in the debug overlay (the Aptimize logo in the top left of the page). Production - Configures the Website Accelerator for maximum production performance and reduces log output to important errors only. (Note: a valid license is installed to switch to Production mode)

logPath [optional]

(Text) The physical directory that WAX should use to store its logs files in. This can be any local or UNC path that the application pool identity has write permissions to.

pageExecutionTimeout [optional] (Number) The length of time in seconds that WAX should wait for the content of requests it is to accelerate to complete. If page execution time exceeds this value, then the user will receive a timeout message. [default = 300]

httpCompressionScheme [optional]

Gzip – The gzip compression scheme will be used to compress resources. Deflate – The deflate compression scheme will be used to compress resources. [default]

httpCompressionForced [optional]

True – Compression will be forced on, even if the browser does not declare that it supports receiving comnpressed content. False – Compression will only be enabled for responses if the browser indicates it supports compression via the Accept-Encoding header.

loopbackPort [optional]

(Number) The integer port number (1-65535) that all requests should be proxied to. This is used in the configuration of WAX as a proxy.

loopbackHostHeader [optional]

(Text) The host header value to use when proxying requests to the specified loopback port as above.



useAlternateAutoVersionUrlFormat [optional]

True - The automatic versioning scheme will be path based. False - The automatic versioning scheme will be query string based. [default]

diskCacheMaxSize [optional]

(Number) An integer value representing the maximum allowable size of the disk cache in megabytes. Iitems will be removed in order from oldest to newest until the size of the cache is under this value. [default = 10000, i.e. 10GB]

diskCacheCleanupInterval [optional]

(Number) An integer value that represents the interval at which the disk cache cleanup process is run, in seconds. [default = 60]

memoryCacheCleanupInterval [optional]

(Number) An integer value that represents the interval at which the memory cache cleanup process is run, in seconds. [default = 1]

cacheMaxMemory [optional]

(Number) An integer value representing the maximum allowable use of memory in megabytes for resource caching purposes. [default = 100]

resourceSetCacheMaxAge [optional]

(Number) The maximum duration in seconds that sets composed of CSS or JS resources should be retained on disk before being removed. [default = 172800, i.e. 48 hours]

pageSpriteCacheMaxAge [optional]

(Number) The maximum duration in seconds that sets composed of HTML image resources should be retained on disk before being removed. [default = 2880, i.e. 8 hours]

cachePath [optional]

(Text) Any local or UNC path can be used to cache combined resources to disk when running in a single server or load balanced web server configuration. Please refer to the section on production deployment on how to use this setting.

resourceRecheckInterval [optional]

(Number) An integer number that defines the interval in seconds at which resources will be rechecked for changes when requested by a browser. (Note: the recheck is done in the background, so changes will sometimes take 2x this interval to show on the client) [default = 60; min = 1]

maxOptimizationsPerSecond [optional]

(Number) An integer number that defines the maximum number of optimizations the WAX should perform per second. This only includes pages that are accelerated by WAX – images and other cacheable resources do not count against this number. [default = 50]

virtualRoot [optional]

(Text) The virtual root path that resources the WAX serves should appear to come from – this will prefix the /wax.axd component of WAX resource URLs. Useful in situations where Layer 7 routing is used to direct traffic to specific sub-cluster in large clustered environments.



defaultCharset [optional] (Text) The default character set to use when processing text content. This is only used when the charset is not explicitly set in the Content-Type header of the response.

siteVersion [optional]

(Integer) An integer number that can be used to signal a global change in the content, causing all resource cache keys to change. This is not normally required, but if browsers are not picking up content changes due to resource URLs not changing then this setting can be used to force an immediate update.

forwardClientAddress [optional]

True – All requests that WAX makes for pages and other resources from the site to accelerate will include an X-Forwarded-For header containing the client address. False – Internal WAX requests will not contain the X-Forwarded-For header (though if any upstream device has already added this header it will still be present). [default]

trustedForwarders [optional]

[Text] – A comma separated list of router addresses that should be trusted to forward the client IP address. If you have a border router that appends the X-Forwarded-For header, you can specify it’s IP address in the trustedForwarders list to have WAX automatically reattach the actual client address to the ASP.NET UserHostAddress property.

runAsProxy [optional] True – Instructs WAX that it should run as a proxy and therefore always fetch and stream content even for URLs that have been excluded. False – WAX will run in integrated mode, where paths that are excluded by a rule will simply be bypassed by the accelerator and be handled as usual by the site. [default]

stealthMode [optional]

True – WAX will bypass all requests for acceleration, unless the user has explicitly enabled it using the query string instruction ?wax=on. False – WAX will accelerate all requests according to the rules defined in the configuration file. [default]

useAbsoluteUrlsInCacheKey [optional]

True – The unique cache key for resources will be calculated using the full URL, including scheme + host name in addition to path and query. False – Only the path and query components of URLs will be used to calculate the unique cache key for resources, except where the hostname differs to that of the incoming request. [default]

includeOriginalImageUrl [optional]

True – WAX will add a new attribute called waxsrc to each HTML image that is combined into an image set containing the original image URL. This property can then be referenced from script if the original URL is required. False – The original image URL will not be available via the waxsrc attribute. [default]

enableQueryStringImageResize [optional]

True – Enables the ability to request an image to be resized by WAX using a query string instruction such as ?waxsize=20x10 (which would resize the image to 20 by 10 pixels). False – The ability to leverage the WAX image scaling engine via the URL query string will be disabled. [default]



includeFromDomains [optional] ThisDomain – Any resource on the root domain of the request will be optimized. SubDomains – Resources only on the exact sub-domain of the request will be optimized. AllDomains – Resources on any domain will be optimized by WAX. SpecifiedDomains – Resources on specified domains only will be optimize (see the SpecifiedDomains section below).

Logging section The logging section allows control over the logging behavior of WAX. The logging element itself allows 4 possible attributes to be defined: logInfoLevel [optional]

Error – Only important errors will be logged by WAX. Errors at this level are also reported via the system event log. [default when in Production Mode] Warning – In addition to errors, any condition that may affect the performance of the site, but which will not affect behavior for end users will appear at this error level. Info – In addition to errors and warning, the Info error level will display other information about the internal workings of the accelerator specific to the site it is installed on. [default when in Development Mode] Trace – Resources on specified domains only will be optimize (see the SpecifiedDomains section below).

retainPerformanceLogDuration [optional] [Number] – The number of hours to retain the performance log information for. [default = 24]

retainErrorLogDuration [optional]

[Number] – The number of hours to retain error log information for. [default = 5] retainDebugLogDuration [optional]

[Number] – The number of hours to retain debug log information for. [default = 5] The logging section also allows the definition of a set of trace keys that can be used to capture specific requests. These are defined as inner elements of the logging element – refer to the Logging and debug trace section for usage information.

Monitoring section The monitoring section controls the behavior of the advanced health monitoring status API, exposed via the URL: /wax.axd/api/status. The following attributes are allowed on the monitoring element: enabled [optional]

False – Health monitoring information will not be available in the status True – Health monitoring information will be available via the status API.

trustedClients [optional]

[Text] – A comma separated list of IP addresses or partial network addresses that are trusted to query the status API. By default, only requests from the localhost address will be allowed.

probeMaxDelay [optional]

[Number] – The maximum number of milliseconds to delay the response of the status API request when queried by an upstream load balancer. [default = 100]



probeCpuFunction [optional] [Number] – A decimal number that should be used for the exponential increase in the probe delay function [default = 2]

probeCpuThreshold [optional]

[Number] – The CPU usage threshold over which probe delay should start increasing according to the probe CPU function. [default = 30]

probeCpuOffset [optional]

[Number] – The offset value to use as a modifier in calculating probe delay once CPU usage has exceeded the probe CPU threshold. [default = 5]

probeLowMemThreshold [optional]

[Number] – The low memory threshold under which probe delay should be increased by the value of probe CPU offset. If memory usage drops to beneath half this number, a delay of twice the probe low mem offset will be applied. [default = 100]

probeLowMemOffset [optional]

[Number] – The offset value to use as a modifier in calculating probe delay once memory usage has dropped under the probe low memory threshold. [default = 5]

ResourceSets section The resourceSets section may contain one or more set elements that define a group of objects that should always appear together. The set element allows two unique properties to be defined: type [required]

ScriptSet – The resource set should be treated as a collection of JavaScrip objects. StyleSheetSet – The resource set is a collection of CSS StyleSheet objects. GifImageSet – The resource set is a collection of images in GIF format (automatically converted). PngImageSet – The resource set is a collection of images in PNG format (automatically converted). JpgImageSet – The resource set is a collection of images in JPEG format (automatically converted).

name [optional] [Text] – The name that this resource set should be known as when referencing it from within any transform rule.

In addition, all feature settings that are applied on custom rules may also be applied to the set element. Global settings will be used by default, then overridden by settings specified on the set element. The set element may contain one or more add elements, which like the set element accepts any feature setting to override the settings defined at higher levels. The add element requires that the path attribute contains either an absolute URL or a URL that is relative to the site root so that it can be pre-fetched by WAX.

SearchEngineCrawlers section The searchEngineCrawlers section may contain one or more add elements that define the user agents of known search crawlers. Any user agent that is not a browser will normally be served the original site content, but by



adding the user agent of search crawlers WAX will also send accelerated content to these agents. This can help improve page rank where the search provider uses page speed as one of the factors in their calculations. The userAgent attribute specified on the add element should be a text string that can be used to uniquely identify a search crawler: <searchEngineCrawlers>

<add userAgent="GoogleBot" />

<add userAgent="MsnBot" />

<add userAgent="Yahoo!" />

</searchEngineCrawlers>

If your site is not publically accessible, this section can be removed entirely from the configuration file.

SpecifiedDomains section The specifiedDomains section allows a select set of domains to be defined that govern the eligibility of resources to be processed by WAX. If the hostname of an object URL does not match an entry in specifiedDomains, then it will be excluded – otherwise, the URL will be tested against any rules that might also apply, and if included will be accelerated. <specifiedDomains>

<add path="example.com"/>

<add path="www.example.com"/>

<add path="images.example.com"/>

</specifiedDomains>

The path attribute is required when defining the list of specified domains.

Rules section The rules section allows a list of location specific rules to be defined that override the global settings. These rules are processed in the order in which they appear (i.e. top to bottom) with the first match terminating further processing, and the settings at that location being applied. Each location specific rule is represented by an add element within the rules section. The add element has 3 primary components: path [required]

[Text] – The pattern that should be matched against when evaluating URLs against this rule. The format of this pattern will depend upon the matchType being used.

matchType [optional]

Contains – The path attribute should be treated as a text fragment, with any URL that contains that fragment considered to be a match. [default] Wildcard – The path attribute should be treated as a wildcard expression, where any asterisk symbol matches any number of characters. To allow a wildcard to match any URL, it must begin and end with an asterisk. Regex – The path attribute is a regular expression that should be tested against the URL for a match.

action [required]

Include – Any resource URL that matches this rule should be included by WAX for acceleration. The type of acceleration applied will depend on the resource type.

Exclude – Any resource URL that matches this rule should be excluded by WAX, allowing the original content to be served unaltered. Strip – The element that a matching URL appears on should be removed from the document wherever it appears. This is useful if you have links that are invalid or missing but you cannot edit the source.

browser [optional]

[Text] – A partial browser name or full browser name + version that the rule should apply exclusively to, e.g. MSIE, MSIE6, Firefox2, Safari.

profileDefault [reserved]

True – The location specific rule is defined by the system as a part of the default for the selected profile. All rules marked with profileDefault=”True” will be removed and re-added when upgrading, or applying a new profile. False – The rule is not a profile default rule. If you wish to adopt a profile default rule as an explicit rule, then you can simply remove the profileDefault attribute rather than specifying False as its value.

In addition to these specific settings, any feature setting may be used on the add element of the rules section.

Transformations The add element of the rules section may also contain a transformations element that allows a set of transform rules to be applied at the location when a match is made: <rules>

<add matchType="Contains" path=".js" action="Include">

<transformations>



</transformations>

</add>

<rules>

There are two types of transformations that can be run on a location specific rule: Raw content transformations This group of transformations are run prior to the content being processed by WAX, so can be used to fix any semantic problems – with for example CSS or HTML – prior to parsing. Valid raw content transforms include: clear – Allows you to clear the content of a resource. This can be useful if you have a resource that you wish to completely replace the existing content. An example of this would be a bootstrapping JavaScript file which separately loads a number of other script files. Instead you could clear the content of this script, then using the insertUrl transform insert the actual content of the scripts that the bootstrapper would normally load. Example: <clear />

autoUrlVersion – Allows you to auto version any URL that matches a particular pattern. This can be useful for ensuring that resources loaded from JavaScript can be URL versioned.

pattern [required] – A regular expression, the URL to capture should be stored in a capture group named <url> (must be XML encoded). with [required] – A regex replace expression to reinsert into the page once auto versioned. The new URL can be added with the substitution token ${url} (must be XML encoded). rootUrl [optional] – The root URL to make all URLs found relative to.

urlBase [optional] – One of Auto, Referrer, or Self. Determines whether URLs found are rooted relative to the document they were found in (Self), or they are relative to their parent document (Referrer), or whether it is automatically determined (Auto). The default is to use Referrer for JavaScript documents, Self for everything else.

Example: <autoUrlVersion urlBase="Referrer" rootUrl="http://www.examle.com"

pattern="<xsl\:include\shref="(?<url>.*?)"\s*/>" with="<xsl:include href="${url}" />" />

insert – Allows you to insert content to the start or the end of a document, this can be useful for changing the behavior of scripts but is particularly useful for altering StyleSheets by inserting styles at the end of a StyleSheet, thereby overriding the behaviors defined earlier in the StyleSheet.

insertionPoint [optional] – Either the Start or End of the document [default = End] content [required] – Specified as the inner text of the element, this text will be inserted at the location identified by insertionPoint. This content should be wrapped in a CDATA section.

Example: <insert insertionPoint="End"> <![CDATA[]]> </insert>

insertUrl – Allows you to insert content from another document to the start or the end of a document. This can

be useful for combining the content of a number of separate files into a single file if the standard WAX

combination techniques aren’t suitable. This can also be used to silently redirect requests for one URL to

another URL.

insertionPoint [optional] – Either the Start or End of the document [default = End] url [required] – The URL of the resource that should be retrieved and inserted into the content body.

Example: <insertUrl insertionPoint="End" url="http://example.com/custom.js" />

replace – Allows you to replace content which matches a particular pattern. This transform is extremely versatile and has a wide range of possible uses. These include altering content that is causing combination errors, changing script behaviours, and altering stylesheets. One common scenario is converting javascript document.write statements which write out script tags ito actual script tags so that those scripts can be combined.

pattern [required] – A regular expression that matches the content to be replaced (must be XML encoded). content [required] – Specified as the inner text of the element, this text will be used to replace the section of the original content that matched the specified pattern. This content should be wrapped in a CDATA section.

Example: <replace pattern="foo"> <![CDATA[bar]]> </replace>

HTML content transformations HTML content transformations run once the raw content has been parsed into an HTML document. This type of transform is typically more efficient than running raw content transformations as they only modify small sections of a document at a time, rather than running regular expressions over the entire document content. For this reason it is recommended that parsed content transformations should be used where possible instead of raw content transformations. clearElement – Allows you to clear the content of a parsed html tag. This is useful for removing certain script blocks from a page, or clearing out the content of a script block before replacing its content with something else via one of the other parsed content transformations.

name [required] – The name of the HTML element to match (one of style, script, img, link, or input).



id – The id of the HTML element to match on. To specify other attributes to match (e.g. href or media) then use id="href=style.css" or id="media=print". You don't need to specify the attribute if you want to match an id e.g. id="foo". pattern – A regular expression that should be tested against the content of the element for a match. This should only be used if an ID does not exist on the element you wish to match (must be XML encoded). skip – If no id is specified, this specifies how many matches to skip past before first applying the transformation. take – if no id is specified, this specifies how many matches to run the transformation for once the first match is found (after the skip setting has been taken into account – [default = 0 which takes all matches]

Example: <clearElement name="script" id="foo" />

insertElement – Allows you to insert content to the start or the end of a matching element. This is useful if you want to append or prepend content to a specific element in an HTML document.

name [required] – The name of the HTML element to match (one of style, script, img, link, or input). id – The id of the HTML element to match on. To specify other attributes to match (e.g. href or media) then use id="href=style.css" or id="media=print". You don't need to specify the attribute if you want to match an id e.g. id="foo". pattern – A regular expression that should be tested against the content of the element for a match. This should only be used if an ID does not exist on the element you wish to match (must be XML encoded). skip – If no id is specified, this specifies how many matches to skip past before first applying the transformation. take – If no id is specified, this specifies how many matches to run the transformation for once the first match is found (after the skip setting has been taken into account – [default = 0 which takes all matches] removeContainer – True to remove the containing element from the document, or False to leave it intact. insertionPoint – The Start or End of the document (default = End). content [required] – Specified as the inner text of the element, this text will be used to replace the section of the original content that matched the specified pattern. This content should be wrapped in a CDATA section.

Example: <insertElement name="script" id="foo" removeContainer="True" insertionPoint="End">

<![CDATA[nothing to see here...]]> </insertElement>

insertHtml – Allows you to insert content at various points in an HTML document. This is useful for injecting styles or script blocks to certain parts of a page.

insertionPoint [required] – The location to insert the content into the document (one of HeadStart, HeadFirstScript, HeadLastScript, HeadEnd, BodyStart, BodyFirstScript, BodyLastScript, BodyEnd). content [required] – Specified as the inner text of the element, this text will be used to replace the section of the original content that matched the specified pattern. This content should be wrapped in a CDATA section.

Example: <insertHtml insertionPoint="BodyEnd"> <![CDATA[My custom footer]]> </insertHtml>

removeElement – Allows you to remove a parsed html tag from a document. This is useful for removing redundant or problematic script and style blocks from a page.

name [required] – The name of the HTML element to match (one of style, script, img, link, or input). id – The id of the HTML element to match on. To specify other attributes to match (e.g. href or media) then use id="href=style.css" or id="media=print". You don't need to specify the attribute if you want to match an id e.g. id="foo". pattern – A regular expression that should be tested against the content of the element for a match. This should only be used if an ID does not exist on the element you wish to match (must be XML encoded). skip – If no id is specified, this specifies how many matches to skip past before first applying the transformation.



take – If no id is specified, this specifies how many matches to run the transformation for once the first match is found (after the skip setting has been taken into account – [default = 0 which takes all matches]

Example: <removeElement name="script" id="foo" />

moveElement – Allows you to move a parsed html tag to another location in a document. This is useful for moving script blocks to a more optimal location.

name [required] – The name of the HTML element to match (one of style, script, img, link, or input). id – The id of the HTML element to match on. To specify other attributes to match (e.g. href or media) then use id="href=style.css" or id="media=print". You don't need to specify the attribute if you want to match an id e.g. id="foo". pattern – A regular expression that should be tested against the content of the element for a match. This should only be used if an ID does not exist on the element you wish to match (must be XML encoded). skip – If no id is specified, this specifies how many matches to skip past before first applying the transformation. take – If no id is specified, this specifies how many matches to run the transformation for once the first match is found (after the skip setting has been taken into account – [default = 0 which takes all matches] insertionPoint [required] – The location in the document to move the element to (one of HeadStart, HeadFirstScript, HeadLastScript, HeadEnd, BodyStart, BodyFirstScript, BodyLastScript, BodyEnd).

Example: <removeElement name="script" id="foo" insertionPoint="BodyEnd" />

replaceElement – Allows you to replace content that matches a particular pattern for a selected element. This transformation, like the more general replace transform has a wide range of uses, but is more appropriate if you have content that you wish to replace that resides in a particular element on a page.

name [required] – The name of the HTML element to match (one of style, script, img, link, or input). id – The id of the HTML element to match on. To specify other attributes to match (e.g. href or media) then use id="href=style.css" or id="media=print". You don't need to specify the attribute if you want to match an id e.g. id="foo". pattern – A regular expression that should be tested against the content of the element for a match. This should only be used if an ID does not exist on the element you wish to match (must be XML encoded). skip – If no id is specified, this specifies how many matches to skip past before first applying the transformation. take – If no id is specified, this specifies how many matches to run the transformation for once the first match is found (after the skip setting has been taken into account – [default = 0 which takes all matches] removeContainer – True to remove the containing element from the document, or False to leave it intact. content [required] – Specified as the inner text of the element, this text will be used to replace the section of the original content that matched the specified pattern. This content should be wrapped in a CDATA section.

Example: <replaceElement name="script" id="foo" removeContainer="True" pattern="red"> <![CDATA[blue]]>

</replaceElement>

Cluster section The cluster section defines the collection of web servers that operate in a cluster to host the target sites. The cluster element itself accepts two attributes that control the behavior of the cache when running in a load balanced cluster: cacheMode [required]

Shared – The path specified in the cachePath attribute is treated as a shared network path that all servers will use to store and find combined resources where an in-memory cache miss occurs.



Replicated – The path specified in the cachePath attribute is treated as a local path, from and to which resources are replicated on demand as a miss occurs in the in-memory cache.

networkPath [optional]

[Text] – The network path component of the share name to use for replication of resources when cacheMode=”Replicated". This should be specified as the share name and any child path the applies. (Windows OS only).

The cluster section should contain two or more node elements that define the actual server details for the cluster. Each node element allows 3 properties to be defined: hostName [required]

[Text] – The host name of the server as displayed by typing “hostname” from a command line interface. bindingIp [optional]

[Text] – The IP address to use for accessing the cache if the hostname does not resolve to an IP address that is used for web hosting.

zone [optional]

[Text] – An arbitrary text value that defines the zone that this node exists in. If your cluster is balanced across multiple geographical locations, you should define 1 zone per location so that WAX knows to scan local nodes for resources first in the event of a memory cache miss.

Feature settings Settings that apply either at the default location or on a location specific rule are described in detail below.

General canonicalization

[Text] – A regular expression that should be applied to the URL prior to it being tested against other rules. This regex should capture just the part of the URL that is considered to be its canonical components into a named capture called <url> (must be XML encoded).

contentType

[Text] – Allows the native content type (MIME type) as returned by the web server to be overridden. This can be useful if content is being emitted by a server side component in the wrong form, since WAX will not process content of one kind where it expects the content type to be another. For example, it is possible to mark all .js files with contentType=”text/javascript” if one or more is appearing as “text/html”.

groupName

[Text] – Defines the name of the group that resources will be added to when combined instead of using the default global group names. This allows objects to be partitioned into common and page specific images for example.

httpFetchTimeout

[Number] – Defines the maximum time in milliseconds that WAX will wait for a resource to be retrieved. All local resources of the site are expected to be returned effectively instantaneously, so if this limit is being hit there is probably something wrong. There are however legitimate cases where a longer timeout is desirable, particularly if WAX is instructed to process resources from external sites.[default = 3000]



rewriteToCdn [Text] – Relocates resources from the current domain onto the specified host or URL root by rewriting all matching URLs. This can be specified as a single hostname (e.g. cdn.example.com) or a root URL (e.g. https://cdn.example.com/images).

CSS optimization shrinkCss

True – CSS blocks in the page and in external StyleSheets will have all redundant whitespace + comments removed. False – CSS will remain in its original form wherever it appears. Note: this disables the ability to use the inlineCssImages setting.

inlineCssImages

True – Background images that are referenced from CSS will be converted to data:uri notation and inlined as base64 data into the CSS for browsers that support it. For Internet Explorer 6 & 7, this feature will use an MHTML reference instead of data:uri notation. False – Background images that are referenced from CSS will remain as URLs instead of base64 data.

maxInlineImageSize

[Number] – The maximum allowable size of base64 encoded data to be inlined using data:uri notation or a MHTML reference. Images that exceed this will limit will remain as URLs.

combineStyleSheets

None – StyleSheet files will not be combined together at this location. All – All StyleSheet files will be combined together, no matter where they appear in the page, and the new combined reference will be inserted at the top of the head section of the document. Consecutive – StyleSheet files that appear as consecutive references (i.e. without inline style blocks or excluded StyleSheet links between) will be combined together and each combined reference inserted to the location where the first StyleSheet in a set appears in the document.

combineInlinedCssImages

Off – Disables the creation of MHTML references for IE6 and IE7 browsers, leaving browsers that support base64 data:uri notation enabled. This setting is automatically applied when the page is requested over HTTPS, since otherwise IE displays a mixed-content warning. PerStylesheet – WAX will produce one MHTML document containing the base64 encoded image data per StyleSheet. PerCombinedStylesheet – WAX will produce one MHTML document containing the base64 encoded image data per combined StyleSheet. [default]

JavaScript optimization shrinkScripts

True – Script files will have all redundant whitespace + comments removed. False – Script files will remain in their original un-minified form.

combineHeadScripts

None – Script files that appear in the head section of the document will not be combined together with other script files. All – All script files found in the head section of the document at this location will be combined together into a single file.



Consecutive – Script files that appear as consecutive references in the head section (i.e. without other inline script blocks or HTML elements between them) will be combined together.

headScriptInsertionPoint

[InsertionPoint] – The location in the HTML document to reinsert the scripts that were combined according to the combineHeadScripts setting. Note: It is possible to relocate scripts from one section to another using this setting (e.g. move head scripts to body end).

combineBodyScripts

None – Script files that appear in the body section of the document will not be combined together with other script files. All – All script files found in the body section of the document at this location will be combined together into a single file. Consecutive – Script files that appear as consecutive references in the body section (i.e. without other inline script blocks or HTML elements between them) will be combined together.

bodyScriptInsertionPoint

[InsertionPoint] – The location in the HTML document to reinsert the scripts that were combined according to the combineBodyScripts setting. Note: It is possible to relocate scripts from one section to another using this setting (e.g. move head scripts to body end).

Insertion points The following insertion points are available wherever an [InsertionPoint] is referred in the settings above: HeadStart – The location in the HTML document immediately after the <head> section open tag. HeadFirstScript – The location in the head section of the document where the first script reference appears. HeadLastScript – The location in the head section of the document where the last script reference appears. HeadEnd – The location in the HTML document immediately before the closing </head> section tag. BodyStart – The location in the HTML document immediately after the <body> section open tag. BodyFirstScript – The location in the body section of the document where the first script reference appears. BodyLastScript – The location in the body section of the document where the last script reference appears. BodyEnd – The location in the HTML document immediately before the closing </body> section tag. FirstReference – The location at which the first object in a named resource set appears. Also used implicitly to group references when the combination mode is Consecutive. Note: If the headScriptInsertionPoint and bodyScriptInsertionPoint are identical, then all scripts will be combined together at that location. It is also possible to use this setting on a location specific rule to move selected scripts to a particular location in the document and have them combined together.

Image optimization combineImages

None – Images that appear as <img> tags in the HTML will not be combined into image sprites. All – All images that appear as <img> tags in the HTML will be combined into an image sprite according to the image format.

imageFormat

Gif – The image will be converted to GIF format before being added to an image sprite or served. Png– The image will be converted to PNG format before being added to an image sprite or served. Jpg – The image will be converted to JPEG format before being added to an image sprite or served. Note: If an image appears on a website in BMP format, it will automatically be converted to JPEG format by WAX to reduce its size. This can be prevented by excluding the image from processing with a rule.



shrinkImages

True – Images will be shrunk where possible, removing unnecessary information like metadata, redundant color information and in the case of JPEG images, reducing the quality to reduce the size of the files.

jpegQuality

[Number] – The quality level to resample JPEG images to (0-100). If retaining the quality of your JPEG images is paramount, then set this value to 100. [default = 85]

size

[Dimensions] – The desired size to scale images to at this location, expressed as dimensions in the form width x height (e.g. 20x10, or 150x12).

Caching cacheableMimeTypes

[Text] – A comma separated list of the MIME types that should be considered cacheable at this location. The default list is: “text/css, text/javascript, application/x-javascript, image/gif, image/png, image/jpeg, image/jpg, image/bmp, image/x-icon, application/x-shockwave-flash, text/x-component”.

resourceClientCacheDuration

[Number] – The duration in seconds that resources in the cacheableMimeTypes list at this location should be cached for on the client before expiring. This is used as a sliding expiry to set the Expires header – i.e. the client will cache the file for this many seconds from when it receives it, whenever that is. [default = 600 for unversioned URLs, i.e. 10 minutes – 7776000 for versioned URLs, i.e. 90 days]

autoVersionUrls

True – URLs at this location will be versioned by appending a query string parameter that is a hash of the contents of the file. The cache duration used for versioned URLs is the greater of resourceClientCacheDuration or 90 days. False – URLs will be left unaltered (clients will cache the item for the full resourceClientCacheDuration interval before rechecking).

proxyCacheable

True – Resources that are cacheable at this location will be marked with the Cache-Control: public header which allows them to be cached by intermediary proxy servers. False – Resources that are cacheable will be marked with the Cache-Control: private header to prevent them from being cached by intermediary proxy servers. [default]

resourceRecheckInterval

[Number] – The time in seconds after which a resource that is in the server cache will be marked for a recheck. When a resource that is marked this way is requested, the existing version in cache will be returned immediately, while a background task refreshes the cached version if it has been modified.

Compression compressableMimeTypes

[Text] – A comma separated list of the MIME types that should be considered compressible at this location. The default list is: “text/html, application/xhtml+xml, text/css,text/javascript, application/x-javascript, text/xml, application/xml, application/json, text/x-component”.



httpCompression Off – WAX will not perform compression at this location. Smallest – WAX will apply the compression technique that results in the smallest file size. Fastest – WAX will apply the compression technique that requires the least processing to perform.

Logging suppressedErrorCodes [optional]

[Text] – A comma separated list of WAX error codes that should be suppressed at this location. If you see an error code in the logs that you wish to silence, you can specify just the number component of this here.



11. Advanced configuration scenarios WAX has considerable flexibility in the way it is integrated into the operational environment. This section covers some of the advanced configuration settings of the product and scenarios in which they might be used.

Special considerations for sites running under HTTPS In general, it is advisable to run only the sections of a website that actually require it under SSL – for example, a login page or areas where users manage personal information are good candidates for using SSL. If the rest of the site is not sensitive however, the user connection should be switched back down to plain old HTTP since this provides significant performance benefits from caching. WAX must also automatically disable the MHTML feature when a page is requested over HTTPS. While requests for these resources are made over HTTPS, IE incorrectly thinks the protocol is MHTML since this is what the URL starts with which causes a mixed mode content warning. If the site is accessed over HTTPS but another device is terminating the SSL connection (e.g. a load balancer or proxy) rather than the website, then WAX needs to be told to disable the MHTML feature explicitly. To do this, add the following setting to the configuration file:

<wax:configuration ... combineInlinedCssImages="Off" ...>

This will disable the use of MHTML resources, which affects only IE 6 & 7 users – all other browsers will still leverage data:uri inlining of images. If there are only parts of a site that are SSL secured, you can specify this setting on a location specific rule instead. This allows MHTML inlining to be used except where it is known that users will access the site over HTTPS.

ISAPI mode vs. HttpModule mode By default, WAX for Windows runs in ISAPI mode. In this mode, incoming requests will be intercepted by an ISAPI filter and the URL rewritten to the WAX request handler. Once received by the WAX handler, the server response content is accelerated and sent back to the browser. This mode typically provides good compatibility with most applications and operating system versions. If your web application runs on IIS7 in integrated mode, you also have the option of running WAX in HttpModule mode. In this mode, no ISAPI filter is installed into the site – instead an HttpModule handles all functions of intercepting incoming requests and accelerating the response. This has the benefit of not requiring the URL to be rewritten, which can reduce the chance of problems with 3

rd party modules such as URL rewriter

components. You can switch from ISAPI mode to Module Mode and back from the Options menu in the WAX configuration tool:



Note: It is also possible to use module mode in classic mode applications or on IIS6, but you must also add a wildcard mapping to the aspnet_isapi.dll in the .NET framework directory. While this will give slightly lower performance than running in ISAPI mode, it may overcome issues with 3

rd party components that would

otherwise not be possible.

Running WAX in proxy mode The default installation of WAX is to run on-server as a module integrated into the target website. It is however also possible to run in an alternative configuration mode as an accelerating proxy. This allows flexibility to work around possible issues with the installation:

You wish to accelerate a site that does not work when WAX runs as a module directly on the site (refer to this issue for an example: SQL Reporting Services SharePoint webpart displays an error when WAX is installed

You wish to accelerate a site that is hosted on a platform not directly supported by WAX (for example Solaris, WebSphere, or ASP.NET 1.1 on IIS)

The method of running WAX in proxy mode differs between the Windows and Linux versions of the product.

WAX for Windows In this mode, you create a new site that acts to receive the original request for a user. It is then possible to configure WAX on this site to act as an accelerating proxy for any other site, including those that use ASP.NET 1.1 which is otherwise not supported. There are 3 options for passing the traffic through the WAX acceleration proxy:

1. Add a new binding to the WAX proxy site and configure your router to direct traffic intended for the target site to this site’s IP address + port instead of the original target.

2. Move the appropriate bindings from the target site to the WAX proxy site, and add a new binding to the target site that will be used by WAX to retrieve the content.

3. Install WAX on a new Windows server, and change network and load balancer routing rules such that requests for the target site(s) are passed through WAX. This effectively turns WAX into an acceleration appliance.

Here's an example configuration based upon method 2 that assumes the target site is bound to http://example.com:80/ in IIS and listening on all IP addresses:

1. Create a new site in IIS with its own physical directory (in this example called WAX_Proxy) 2. Install Website Accelerator on the WAX_Proxy site 3. Browse to the site root directory and open wax.config for editing 4. Add the section below as an inner element of wax:configuration (modify the to, from and hostname

attributes according to your setup)

<loopbackRules>

<add from="*" to="http://127.0.0.1:30001" />

</loopbackRules>

5. Save the file, and hit F5 in the WAX configuration tool to verify that the config is valid 6. Run IIS manager, and move the bindings from the target website to the WAX_Proxy site (you will need

to remove them from the target and add them to the WAX_Proxy site)



7. Add a new binding to the target site for 127.0.0.1 on port 30001 to match the loopbackRules above 8. Open a browser and navigate to your site to see it accelerated by WAX

* Note: If you are running SharePoint, you must add an alternate access mapping for any new bindings that are added to the site (e.g. 127.0.0.1:30001). This process is covered in the SharePoint documentation.

WAX for Linux The configuration of WAX for Linux in reverse proxy mode leverages the Apache mod_proxy module. Please contact Aptimize for assistance in configuring Apache + WAX in this mode: [email protected].

Additional steps for SSL enabled sites If your site is configured to use SSL, you must also add the SSL certificate and required bindings to the WAX proxy site. In this case you should configure your target site to use an HTTP only bindings which reduces the load on the server due to SSL encryption.

Changing the default WAX log location By default, the WAX log files are stored on the system drive where WAX was installed (e.g. C:\Program Files\Aptimize\WebsiteAccelerator\Logs). If you have a separate logical drive that is used to hold log files of OS components or other applications, it is recommended that you configure WAX to use this drive also. This can be achieved using the logPath setting, e.g.: <wax:configuration ... logPath=”E:\Logs\WAX” ...>

WAX will rotate the log files it produces to prevent them from taking up an increasingly large amount of disk space, but if you have trace level logging enabled at a global level on a production site, this can still result in a very large amount of data in the log files. Moving these log files to a separate drive will prevent the system drive from running out of space.

Configuring WAX advanced health monitoring The Aptimize Accelerator monitoring interface provides insight into the health and performance of the accelerator in an operational environment. This information is published in XML form via the URL http://host/wax.axd/api/status where host is the hostname used to access your site.

Configuring the health monitoring interface Gathering information from the monitoring interface requires two simple configuration steps to make it accessible:

1. Add trusted network clients to the list of trustedClients 2. Add the application pool user identity to the Performance Monitor Users group

The exact steps for number 2 vary depending on which version of Windows you are running – detailed instructions are below.

mailto:[email protected]

http://host/wax.axd/api/status



1. Add trusted network clients to the list To ensure that the information is only available to trusted network clients, you must define the IP addresses or ranges that are allowed to access the monitoring API. This is done using the trustedClients attribute of the monitoring element in the wax.config file. An example configuration for this section is shown below: <wax:configuration ... > <monitoring enabled="True" trustedClients="10.10.0.0,172.16.1.254" /> </wax:configuration> These settings enable the monitoring interface, and allow any machine on the 10.10 network and the machine at 172.16.1.254 to access the monitoring data feed.

2. Add the application pool user identity to the Performance Monitor Users group To enable the Aptimize Accelerator to gather system performance information, the application pool user identity that the website runs under must be a member of the Performance Monitor Users group. Adding the application pool user identity to this group differs depending upon the operating system used. Once this user has been added to the Performance Monitor Users group the application pool must be restarted to cause the Aptimize Accelerator to start sampling the performance counters. Windows 2003 Server / Windows 2008 R1 Server For the site you want system performance information for, determine the user account that the application pool is running as from IIS Manager. For Windows 2003 Server, you must navigate to the Identity tab of the application pool properties dialog – on Windows 2008 Server the user identity is visible from the Application Pools list. To add the user to the Performance Monitor Users group, you must use the Computer Management administration console (Start -> Run -> compmgmt.msc). Expand the Local Users and Groups node, select the Groups node, then right-click Performance Monitor Users and select Add to Group.

Select the local computer as the location if the application pool is using an in-built account, or the appropriate domain if it is a domain account, then enter the name of the user account and click Check Names. If the account is found by the operating system it will change the formatting of the name – once this is done click OK.



Once you have added the user account to the Performance Monitor Users group, you must recycle the application pool for the changes to become visible to the Aptimize Accelerator. Windows 2008 R2 Server / Windows 7 On Windows 2008 R2 Server and Windows 7 operating systems, the default user identity use for all application pools is ApplicationPoolIdentity. This represents a virtual account that is created by IIS using the name of the application pool prefixed with IIS AppPool – for example, the SharePoint application pool in the screenshot below can be referred to in ACL lists using "IIS AppPool\SharePoint".

To add the correct user account, you must select the local computer from Locations and then enter the name of the virtual account as demonstrated in the screenshot below. This dialog is accessed via the Computer Management administration console (refer to the instructions for Windows 2003 / 2008 R1 above).



Configuring WAX for use with ADC appliances WAX is designed to work seamlessly in conjunction with Application Delivery Controller appliances. There is typically some crossover of responsibility between WAX and an ADC, but the general recommendation is to allow WAX to perform all acceleration functions except for compression which should be delegated to the ADC. To do this, disable compression within WAX using the httpCompression setting: <wax:configuration ... httpCompression=”Off” ...>

You may also need to enable compression within your ADC appliance. Please refer to the documentation for your particular make and model for guidance on how to configure this. You should inspect the HTTP traffic to ensure that all text based resources are being correctly compressed afterward – this can be confirmed by the presence of a header called “Content-Encoding” on the response. If compression is enabled, this should contain the value of either gzip or deflate.

Aptimize Accelerator - Advanced User Guide - July 2010

Documents

Transcript of Aptimize Accelerator - Advanced User Guide - July 2010