Offloading Media File Downloads to an External Web Server

Overview

When configuring the EchoSystemServer for use with an external web server for content playback (see Using an External Web Server for Content Playback), downloadable static media, such as .MP3 and .M4V files are still served through the built-in Jetty web server. In deployments that experience regular high load, having these files served through Jetty can have a serious impact on application performance. The following document covers how to offload the serving of these files to an external web server that has previously been configured for ESS content playback.

The following web server technology is supported for this use:

• Microsoft IIS 7
• Apache

URL Rewrites

The essence of this change involves the use of URL rewrites. When a request comes to the ESS to download a static media file, this request is then re-directed to the external web server (which already has access to the appropriate files in the active content directory defined by your ESS) to be served up for download. Each web server software package has different means of enabling URL rewrites, and the steps below make the assumption that the URL rewrite module or feature is already installed for your instance.

Consult your web server software configuration guide for further details on enabling URL rewrite capability, or contact Echo360 Technical Support for guidance.

Configuring an IIS Web Server

These instructions assume that you have already installed the Internet Information Services (IIS) packages on the Windows host and have the service configured for use with ESS content playback. Before processing, ensure that the URL Rewrite Module version 2.0 is installed. You can obtain it here:  http://www.microsoft.com/web/gallery/install.aspx?appid=urlrewrite2. Additionally, make sure .NET is installed with IIS and .NET Roles is enabled and running under ASP.NET in the Features View tab in the IIS manager.

Begin by opening the Internet Information Services (IIS) Manager, located under Control Panel > Administrative Tools.

1. On the left panel, expand your domain (or computer name) in the list.
2. Expand the Sites option, then click on Default Web Site.
3. On the Features View tab, double-click on URL Rewrite.
4. In the Actions panel on the right side of the screen, click on Add Rule(s)...
5. In the window that appears, under the Outbound Rules section select Blank rule and then the OK button. You will then be presented with the page to create a new outbound rule.
6. Set the name of the rule to "Allow Podcast Download" (without the quotations).

7. Use the drop-down to select <Create New Precondition...> and populate the following values for the new Precondition: 

   Field	Value
   Name	Only Match Podcast
   Using	Regular Expressions
   Logical Group	Match All

8. Click the Add.. button to add a new condition, and populate the following values:

   Field	Value
   Condition Input	{RESPONSE_CONTENT_TYPE}
   Check if input string	Matches the Pattern
   Pattern	^audio/mpeg
   Ignore case	Checked

9. Press OK to complete adding the condition.

10. Press OK to complete adding the precondition.

11. Expand the Match section, and populate the following values:

    Field	Value
    Matching Scope	Server Variable
    Variable Name	RESPONSE_Content_Disposition
    Variable Value	Matches the Pattern
    Using	Regular Expressions
    Pattern	(.*)
    Ignore Case	Checked

12. Expand the Conditions section.

13. Set the Logical grouping to  Match All.
14. Ensure the Track capture groups across conditions option at the bottom of the pane is checked.

15. Click on the Add... button. A window will appear to add a new condition. Populate the following values:

    Field	Value
    Condition Input	{QUERY_STRING}
    Check if input string	Matches the Pattern
    Pattern	^download
    Ignore case	Checked

16. Press OK to complete adding the condition.

17. Expand the Actions section and populate the following values:

    Field	Value
    Action Type	Rewrite
    Value	attachment;filename=media.mp3
    Replace existing server variable value	Checked
    Stop processing on subsequent rules	Unchecked

18. In the Action panel on the right side of the screen, click on Apply. If successful, you'll see the message: "The changes have been successfully saved."
19. Click the Back to Rules link.
20. Click on Add Rule(s)... again to add another rule.
21. Set the name of the rule to "Allow Vodcast Download" (without the quotations).

22. Use the drop-down to select <Create New Precondition...> and populate the following values for the new Precondition: 

    Field	Value
    Name	Only Match Vodcast
    Using	Regular Expressions
    Logical Group	Match All

23. Click the Add.. button to add a new condition, and populate the following values:

    Field	Value
    Condition Input	{RESPONSE_CONTENT_TYPE}
    Check if input string	Matches the Pattern
    Pattern	^video/m4v
    Ignore case	Checked

    Note for IIS 8.5

    Though not supported at this time, if you are using IIS 8.5 the match pattern should be set to "^video/mp4" rather than "^video/m4v".

24. Press OK to complete adding the condition.

25. Press OK to complete adding the precondition.

26. Expand the Match section, and populate the following values:

    Field	Value
    Matching Scope	Server Variable
    Variable Name	RESPONSE_Content_Disposition
    Variable Value	Matches the Pattern
    Using	Regular Expressions
    Pattern	(.*)
    Ignore Case	Checked

27. Expand the Conditions section.

28. Set the Logical grouping to  Match All.
29. Ensure the Track capture groups across conditions option at the bottom of the pane is checked.

30. Click on the Add... button. A window will appear to add a new condition. Populate the following values:

    Field	Value
    Condition Input	{QUERY_STRING}
    Check if input string	Matches the Pattern
    Pattern	^download
    Ignore case	Checked

31. Press OK to complete adding the condition.

32. Expand the Actions section and populate the following values:

    Field	Value
    Action Type	Rewrite
    Value	attachment;filename=media.m4v
    Replace existing server variable value	Checked
    Stop processing on subsequent rules	Unchecked

33. In the Action panel on the right side of the screen, click on Apply. If successful, you'll see the message: "The changes have been successfully saved."
34. Click the Back to Rules link.
35. The two new outbound rules should be shown in the bottom panel.
36. Restart the IIS service for these changes to take effect, and proceed to the section below Enabling External Media Downloads on the ESS. 

These instructions assume that you have already installed the appropriate Apache web server packages and have service already configured for use with ESS content playback. You will also need to have the mod_rewrite and  mod_header Apache modules installed. Refer to the Apache or system documentation for instructions on how to do this for your platform.

1. Make a backup copy of the existing httpd.conf file (typically located under /etc/httpd/conf)

2. Enable the mod_rewrite and mod_header Apache modules. This is typically accomplished by adding lines like this to the httpd.conf file, but the specifics will depend on your platform:

   LoadModule rewrite_module modules/mod_rewrite.so
   LoadModule headers_module modules/mod_headers.so

3. Locate the existing echocontent Alias section of the httpd.conf file and add the following between the <Directory> tags:

   RewriteEngine On
   RewriteCond %{QUERY_STRING} ^download
   RewriteCond %{REQUEST_FILENAME} mp3$ [OR]
   RewriteCond %{REQUEST_FILENAME} m4v$
   RewriteRule ([^/]+)$ - [E=dlfilename:$1]
   Header onsuccess set Content-Disposition "attachment;filename=\"%{dlfilename}e\"" env=dlfilename

   This should result in a stanza similar to this:

   Alias /echocontent "/var/www/echocontent"
   <Directory "/var/www/echocontent">
       Options Indexes MultiViews
       AllowOverride None
       Order allow,deny
       Allow from all
   	RewriteEngine On
   	RewriteCond %{QUERY_STRING} ^download
   	RewriteCond %{REQUEST_FILENAME} mp3$ [OR]
   	RewriteCond %{REQUEST_FILENAME} m4v$
   	RewriteRule ([^/]+)$ - [E=dlfilename:$1]
   	Header onsuccess set Content-Disposition "attachment;filename=\"%{dlfilename}e\"" env=dlfilename
   </Directory> 

   In this example, /var/www/echocontent is the location of the mount point created for the active content directory. Your configuration will vary.
    

4. Restart the Apache service for these changes to take effect, and proceed to the section below Enabling External Media Downloads on the ESS.

These instructions assume that you have already installed the appropriate NGINX packages and have the service running with the default configuration. The nginx application comes bundled with a URL rewrite module by default. Normally no action will be necessary to enable it.

1. Make a backup copy of your configuration file before proceeding. By default, the configuration file is named  default.conf  and placed in the directory  /etc/nginx/conf.d

2. Add the following directives to the location block referencing the URL alias for your ESS content (e.g., location /echocontent):
   

   if ($query_string ~* ^download)
   { set $target $1; add_header Content-Disposition 'attachment; filename="$target"'; }

   This should result in a stanza similar to this:
   

   location /echocontent
   { 
   	alias /usr/share/nginx/echocontent;
   	if ($query_string ~* ^download)
   	{ set $target $1; add_header Content-Disposition 'attachment; filename="$target"'; }
   }

   In this example, /usr/share/nginx/echocontent is the location of the mount point created for the active content directory. Your configuration will vary.
    

3. Restart the NGINX service for the changes to take effect, and proceed to the section below Enabling External Media Downloads on the ESS.

The final step involves a change to one of the configuration files on the ESS host. You'll need access to the host the EchoSystem Server application is running on.

1. On the host file system, use a text editor to open the file labeled wrapper.conf, located by default under /usr/local/echo360/server/etc on Linux and C:\Program Files\Echo360\server\etc on Windows

2. Add the following line within the # Java Additional Parameters section:

   wrapper.java.additional.981=-Decho.direct.external.download=true

   Ensure that this line is inserted in numeric order relative to the other wrapper.java.additional values. The wrapper.conf file cannot have multiple wrapper.java.additional values with the same number. For example, if the block contained the following stanzas:
   
   

   wrapper.java.additional.401=-Dlogback.configurationFile=etc/jetty.logging.cfg.xml
   wrapper.java.additional.402=-Dorg.apache.tapestry.enable-reset-service=true
   wrapper.java.additional.1012=-XX:MaxGCPauseMillis=1000
   wrapper.java.additional.1021=-Xloggc:logs/gc.%WRAPPER_TIME_YYYYMMDD_HHIISS%.log

    This line would be inserted like so:
   
   

   wrapper.java.additional.401=-Dlogback.configurationFile=etc/jetty.logging.cfg.xml
   wrapper.java.additional.402=-Dorg.apache.tapestry.enable-reset-service=true
   wrapper.java.additional.981=-Decho.direct.external.download=true
   wrapper.java.additional.1012=-XX:MaxGCPauseMillis=1000
   wrapper.java.additional.1021=-Xloggc:logs/gc.%WRAPPER_TIME_YYYYMMDD_HHIISS%.log

   
   

3. Save the wrapper.conf file, and restart the ESS service