Apache

Table of Contents

Installation

Windows

The Windows Apache 2.4 build uses the Apache Lounge 64bit distribution.

Unzip the apache_mod_smooth_streaming-1.x.y.zip to c:\Apache24 and copy the mod_smooth_streaming.so to your Apache's modules directory.

When using the Apache distribution from Apache Lounge the directory structure should look like this, after having copied the mod_smooth_streaming.so module to the right location:

Directory Use
C:\Apache24\modules Location of mod_smooth_streaming.so
C:\Apache24\conf Location of httpd.conf

To load the module and add the necessary configuration to also load your license key, add the following two lines to Apache's httpd.conf:

LoadModule smooth_streaming_module modules/mod_smooth_streaming.so
Include "conf/usp-license.conf"

Also, in your httpd.conf, uncomment the second line shown below:

#Virtual hosts
#Include conf/extra/httpd-vhosts.conf

So that it will look like this (and tells Apache to include the virtual hosts specified in httpd.vhosts.conf):

#Virtual hosts
Include conf/extra/httpd-vhosts.conf

The actual conf/extra/httpd-vhosts.conf-file should already be in place, but the file conf/usp-license.conf needs to be created and should contain the following (where <your-actual-license-key> equals your actual license key):

UspLicenseKey <your-actual-usp-license-key>

Lastly, in the configuration of your virtual host, AddHandler and UspHandleIsm should be added. This is explained as part of the Virtual host configuration.

Please note that you need the install the redistributable C++ 2012 VC Package (64 bits) if you do not have this installed already.

Linux

See OS Specific Installation, where you will find installation instructions for Amazon Linux, Debian, CentOS and Ubuntu. Please have a look at the Apache Configuration section below as well.

Configuration

License key

Streaming requires a License Key to be present in the Apache configuration. The preferred way is to create a file that is automatically loaded when Apache starts.

If you're running Windows and followed the installation instructions for Windows, which you can find above, Apache is already configured to load the license key when it starts.

For Linux, see our documentation on Apache License Key for the proper configuration.

MPM model

This only applies to Apache installations running on Linux. On most Linux platforms, the default MPM model in Apache 2.4 is most likely 'event'. Please make sure this is changed to either 'worker' or 'process'. See the Apache documentation for more information on MPM models and your OS/package manager on how to change the MPM model. In Ubuntu, for example, this can be done with sudo a2dismod mpm_event followed by sudo a2enmod mpm_worker.

Module loading

If you're running Windows and followed the installation instructions for Windows, which you can find above, Apache is already configured to load the smooth_streaming_module.

On Debian/Ubuntu this is done by adding the following line to your Apache configuration:

LoadModule smooth_streaming_module /usr/lib/apache2/modules/mod_smooth_streaming.so

It can be added to the LoadModule instruction in the /etc/apache2/modules-enabled directory on Ubuntu (apt-get installs a .load and .conf file).

If you're using CentOS, the line that needs to be added looks slightly different:

LoadModule smooth_streaming_module modules/mod_smooth_streaming.so

The location where to add this line on CentOS is different as well. Add it to the LoadModule instructions in the server config: /etc/httpd/httpd.conf.

Virtual host

Next, we're going to tell Apache that files ending in '.ism' and '.isml' are going to be handled by the module. If you want make the presentations available for progressive download then you also have to add the '.mp4' extension.

The configurations below apply to both the Windows and the Linux platform, though the exact location of the Virtual Host configuration will differ for both of these platforms and between different Linux distributions as well. For more information on configuring virtual hosts, please consult Apache's official documentation on the VirtualHost directive.

To enable the module for a virtual host the following should be added as part of a specific virtual host's configuration:

AddHandler smooth-streaming.extensions .ism .isml

The last step is to enable the smooth_streaming_module for a location. If you want to always have the module handle the requests that it supports, you can simply add a single location to the virtual host's configuration:

<Location />
  UspHandleIsm on
</Location>

Important

The UspHandleIsm configuration token MUST be specified in a <Location> directive, not in a <Directory> directive.

Also, on CentOS, to allow the use of multiple virtual hosts the following should be added in the server config located at /etc/httpd/httpd.conf:

NameVirtualHost *:80

If you need more fine grained control, please see the 'More detailed configuration' below. To ensure you have a bare minimum of security in place, please read through the Apache documentation's security tips.

Cross domain access

One other thing that you will need to configure as part of your virtual host configuration, is setting the Cross-Origin Resource Sharing (CORS) headers. These headers are necessary for HTML5 based playout scenarios in which the (Javascript) player and the content are hosted on different domains. If these headers are not present in such a scenario, playout won't work. To set the CORS header correctly, simply add the following lines to Unified Origin's virtual host configuration:

# Necessary for Media Source Extensions (MSE)
Header always set Access-Control-Allow-Headers "origin, range"
Header always set Access-Control-Allow-Methods "GET, HEAD, OPTIONS"
Header always set Access-Control-Allow-Origin "*"
Header always set Access-Control-Expose-Headers "Server,range"

When the player and the content are hosted on different domains, similar information needs to be communicated for playout scenarios using Flash (Adobe HTTP Dynamic Streaming) or Silverlight (Microsoft HTTP Smooth Streaming). For such playout scenarios to work, two files need be hosted in virtual host's DocumentRoot. Preconfigured versions of those files can be downloaded here: crossdomain.xml (for HDS) and clientaccesspolicy.xml (for Smooth).

Live streaming

When using the webserver module for ingesting live streams, you have to take special care about various timeout settings.

Since a long-running HTTP POST is used to transfer the audio/video from the encoder to the webserver, we don't want Apache to close the connection when certain timeouts are reached.

Make sure and verify that LimitRequestBody is set to 0 and in the case of using mod_reqtimeout that the timeout values are sane. In case of the latter, please note that you need to update the global RequestReadTimeout values.

Overriding the values in a virtual host does not work.

LimitRequestBody 0
<IfModule reqtimeout_module>
   RequestReadTimeout header=0 body=0
</IfModule>

Specifics for Expression Encoder 4

If you plan on encoding live streams with Expression Encoder 4 you also have to configure what you return as the Server HTTP response Header. The default is Full which sends information about the OS-type and compiled in modules. In your /etc/apache2/conf.d/security:

ServerTokens Full

Specifics for Media Excel HERO

The HERO encoder requires KeepAlive in the HTTP responses. If it's not present then it closes the connection and doesn't start sending the stream. Look for the KeepAlive tag in the Apache configuration and change it to 'On'.

KeepAlive On

Attention

Please install your License Key now, otherwise streaming will not work!

After restarting your web server, you can continue with Verifying Your Setup.

More detailed configuration

If you need to control the functionality in more detail then you can use the regular expression LocationMatch and enable or disable functionality.

Enable just-in-time packaging for VOD (.ism) and Live (.isml):

<LocationMatch "\.[is]sml?/">
  UspHandleIsm on
</LocationMatch>

Enable just-in-time packaging for MP4:

<LocationMatch "\.mp4/">
  UspHandleIsm on
</LocationMatch>

The module can also handle requests for files packaged with the F4FPackager (mod_f4fhttp). To enable this you have to add the following configuration to rewrite files ending in SegNNN-FragNNN with mod_smooth_streaming:

<LocationMatch "Seg[\d]+-Frag[\d]+$">
  UspHandleF4f on
</LocationMatch>

Serve .mp4 files through Unified Origin. This may be useful for playout of statically stored dref-ed MP4 files and/or playout of pseudo streaming (mod_h264_streaming).

<LocationMatch "\.mp4$">
  SetHandler smooth-streaming.extensions
</LocationMatch>

Please note that Apache's Alias directive does not mix with the Origin module. Instead of using the Alias directive, you may want to use a Virtual Host with the DocumentRoot set to the directory-path of the Alias.

Prevent the download of media files

In order to prevent the download of (source) mediafiles, add the following to your webserver config.

<LocationMatch "\.(ismv|isma|ismt)$">
  deny all
</LocationMatch>

When the source content is MP4 then the rule can be adapted to .mp4 as well.

Options

The options apply to the VirtualHost directive.

Options related to content generation:

Option Description
UspLicenseKey The USP license key, the default is to place this in conf.d/usp-license.conf (see Apache License Key).
UspHandleIsm Set to 'on' to enable mod_smooth_streaming functionality (see above).
UspHandleF4f Set to 'on' to enable mod_f4fhttp functionality (see above and Ingest F4M).
UspIssPassThrough Set to 'on' to pass through MP4 fragments directly to Smooth Streaming (see IIS passthrough).
UspPreferStatic Set to 'on' to prefer static files over dynamically generated files (see IIS passthrough).
UspEnableMMAP Set to 'off' to disable use of memory-mapping (see below).
UspSkipRewrite Set to 'on' to skip the internal rewrite rules (see below).
UspDynamicTimeShiftBufferDepth Set to 'on' to update the @timeShiftBufferDepth attribute dynamically (see below).

Option related to content location:

Option Description
IsmProxyPass Pass .ism to proxy (a virtual path and URL), see HTTP Proxy.

Options releated to secure AWS S3 access:

Option Description
S3SecretKey The AWS secret key (see Using webserver directives for S3 authentication).
S3AccessKey The AWS access key (see Using webserver directives for S3 authentication).
S3Region The AWS region of the bucket (see Using webserver directives for S3 authentication).

The directive UspEnableMMAP controls whether the webserver module uses memory mapped I/O. By default this is on.

You can configure this per directory. E.g. to disable the use of memory mapping for the directory 'path-to-nfs-files' you can specify the following:

<Directory "/path-to-nfs-files">
  UspEnableMMAP Off
</Directory>

The directive UspSkipRewrite controls whether the internal rewrite rules are skipped. By default this is off.

This is an advanced setting and generally not recommended to turn on.

<Directory "/path-to-files">
  UspSkipRewrite On
</Directory>

Lastly, it is also possible to setup Custom HTTP Status codes (Apache).

The UspDynamicTimeShiftBufferDepth option changes how the @timeShiftBufferDepth attribute is set in the MPEG-DASH manifest: the @timeShiftBufferDepth attribute is updated dynamically according to the available time window and capped at the dvr_window_length.

Warning

This option is deprecated.