Offloading Media File Downloads to an External Web Server

In this section:

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
Microsoft IIS 6 does not support URL rewrites and, therefore, is not supported for this configuration.
 
This document also covers the configuration of NGINX, but it is not officially supported at this time. 

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: 

    FieldValue
    NameOnly Match Podcast
    Using

    Regular Expressions

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

    FieldValue
    Condition Input{RESPONSE_CONTENT_TYPE}
    Check if input string

    Matches the Pattern

    Pattern^audio/mpeg
    Ignore caseChecked
  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:

    FieldValue
    Matching ScopeServer Variable
    Variable NameRESPONSE_Content_Disposition
    Variable ValueMatches the Pattern
    UsingRegular Expressions
    Pattern(.*)
    Ignore CaseChecked
  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:

    FieldValue
    Condition Input{QUERY_STRING}
    Check if input string

    Matches the Pattern

    Pattern^download
    Ignore caseChecked
  16. Press OK to complete adding the condition.
  17. Expand the Actions section and populate the following values:

    FieldValue
    Action TypeRewrite
    Value

    attachment;filename=media.mp3

    Replace existing server variable valueChecked
    Stop processing on subsequent rulesUnchecked
  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: 

    FieldValue
    NameOnly Match Vodcast
    Using

    Regular Expressions

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

    FieldValue
    Condition Input{RESPONSE_CONTENT_TYPE}
    Check if input string

    Matches the Pattern

    Pattern^video/m4v
    Ignore caseChecked

    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:

    FieldValue
    Matching ScopeServer Variable
    Variable NameRESPONSE_Content_Disposition
    Variable ValueMatches the Pattern
    UsingRegular Expressions
    Pattern(.*)
    Ignore CaseChecked
  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:

    FieldValue
    Condition Input{QUERY_STRING}
    Check if input string

    Matches the Pattern

    Pattern^download
    Ignore caseChecked
  31. Press OK to complete adding the condition.
  32. Expand the Actions section and populate the following values:

    FieldValue
    Action TypeRewrite
    Value

    attachment;filename=media.m4v

    Replace existing server variable valueChecked
    Stop processing on subsequent rulesUnchecked
  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. 

Configuring an Apache Web Server

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.

Configuring an NGINX Web Server

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.

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

 
Â