How to Configure (Unified Origin)

Note

Our software requires a license key. How to specify your license key for Apache is explained as part of Setting up a virtual host (and specifying your license key) on this page. For more info, see License Key Information.

Basic Apache configuration on Linux

After you have installed our software and Apache on your Linux distribution of choice, you still need to configure several things before you can successfully stream video. First of all, you will need to make sure the correct Apache modules are enabled:

For more info on loading modules into Apache, please see LoadModule.

After you have correctly configured the modules, setting up a virtual host (which includes specifying the license key that Apache needs to load) will be the final step before you have a fully working video streaming setup: Setting up a virtual host (and specifying your license key).

Ensure 'headers' module is enabled

Amazon Linux 2 / CentOS / RedHat

First, check if headers module is enabled or not (if headers_module is not present in the list that is printed, the module is not enabled):

sudo apachectl -M | sort

Then, if headers module is not enabled, enable it. To do this, open /etc/httpd/conf.modules.d/00-base.conf in a text editor to uncomment the line for headers_module.

So change this:

#LoadModule headers_module modules/mod_headers.so

Into this:

LoadModule headers_module modules/mod_headers.so

And save (plus note that these changes will only take effect after a restart of Apache).

Debian / Ubuntu

First, check if headers module is enabled or not:

sudo a2query -m headers

Then, if headers module is not enabled, enable it.

sudo a2enmod headers

Note that these changes will only take effect after a restart of Apache.

Set MPM model to 'worker', not 'event'

On most Linux distributions, the default MPM model in Apache 2.4 is 'event'. Please make sure this is changed to either 'worker' or 'prefork'. See the Apache documentation for more information on MPM models.

Amazon Linux 2 / CentOS / RedHat

First, check which MPM model Apache is currently using:

sudo apachectl -M | sort

Then, Apache is using the MPM model 'event', change it to 'worker' (or 'prefork'). To do this, open /etc/httpd/conf.modules.d/00-mpm.conf in a text editor to uncomment the line for mpm_worker_module and comment out the one for mpm_event_module:

#LoadModule mpm_prefork_module modules/mod_mpm_prefork.so

#LoadModule mpm_event_module modules/mod_mpm_event.so
LoadModule mpm_worker_module modules/mod_mpm_worker.so

And save (plus note that these changes will only take effect after a restart of Apache).

Debian / Ubuntu

First, check which MPM model Apache is currently using:

sudo a2query -M

Then, Apache is using the MPM model 'event', change it to 'worker' (or 'prefork'):

sudo a2dismod mpm_event
sudo a2enmod mpm_worker

Note that these changes will only take effect after a restart of Apache.

Enable 'mod_smooth_streaming' and specify license key

If you have just installed the 'mod_smooth_streaming' module, you still need to enable it.

Amazon Linux 2 / CentOS / RedHat

If you have just installed the 'mod_smooth_streaming' module, you still need to enable it. Checking whether it is already installed is unnecessary, but, in case you event want to, you can do so like this (if smooth_streaming_module is not present in the list that is printed, the module is not enabled):

sudo apachectl -M | sort

To enable the module, open /etc/httpd/conf/httpd.conf in a text editor to add the following two lines (where </path/to/usp-license.key> corresponds to the actual path to the file that contains your license key).

LoadModule smooth_streaming_module modules/mod_smooth_streaming.so
UspLicenseKey </path/to/usp-license.key>

And save (plus note that these changes will only take effect after a restart of Apache).

Debian / Ubuntu

If you have just installed the 'mod_smooth_streaming' module, you still need to enable it. Checking whether it is already installed is unnecessary, but, in case you event want to, you can do so like this (if smooth_streaming_module is not present in the list that is printed, the module is not enabled):

sudo apache2ctl -M | sort

Note

Do not use a2query to check whether 'mod_smooth_streaming' is enabled, because the module will not be listed in the results even if it is active.

To enable the module:

sudo a2enmod mod_smooth_streaming

Note that these changes will only take effect after a restart of Apache.

Basic Apache configuration on Windows

After you have installed Unified Origin on Windows, the three directories that we will be focussing on for the configuration of Apache are the following:

Directory Importance
C:\Apache24\modules Location of mod_smooth_streaming.so
C:\Apache24\conf Location of httpd.conf (general config)
C:\Apache24\conf\extra Location of httpd-vhosts.conf (virtual host)

First, we will enable the 'headers' module by using a plain-text editor to uncomment the below line in httpd.conf:

#LoadModule headers_module modules/mod_headers.so

So that it looks like this:

LoadModule headers_module modules/mod_headers.so

Then we will add the following line to httpd.conf to instruct Apache to load the mod_smooth_streaming.so:

LoadModule smooth_streaming_module modules/mod_smooth_streaming.so

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

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

So that it will look like this (and will tell Apache to include the virtual host configuration specified in httpd-vhosts.conf):

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

Setting up a virtual host (and specifying your license key)

After the Basic Apache configuration on Linux or Basic Apache configuration on Windows, you will need to set up a virtual host in Apache to complete a working video streaming setup.

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.

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.

Note

If you want to make use of multiple virtual hosts on CentOS, you need to add the following to /etc/httpd/httpd.conf:

NameVirtualHost *:80

Specifying your license key

To start, we will first specify our license key in our virtual host file. Note that this must be done outside of the actual virtual host configuration. How you need to specify is slightly different on Linux and Windows, with both are explained below. This is the only part where considerable differences exist between setting up your virtual host on these two platforms. The rest of the configuration can be considered universal.

Specifying license on Linux

To specify your license key on Linux, add the UspLicenseKey directive to the file that contains your virtual host configuration, but add it outside of the configuration of the virtual host itself. Use the directive to point to the file in which you have stored your license key as shown below (where </path/to/usp-license.key> should be replaced to point to the correct location):

UspLicenseKey </path/to/usp-license.key>

<VirtualHost *:80>

  # Rest of config

</VirtualHost>

Specifying license on Windows

To specify your license key on Windows, first create a file called usp-license.conf inside the C:\Apache24\conf directory. This file should contain the UspLicenseKey directive and your full license key. It should look like so (where <your-actual-license-key> should be replaced by your actual license key):

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

Then you need use the Include directive inside the file that contains your virtual host configuration (httpd-vhosts.conf). Make sure to add this directive outside of the configuration of the virtual host itself, and use it to to include the contents of the file you have just created into the configuration:

Include "conf/usp-license.conf"

<VirtualHost *:80>

  # Rest of config

</VirtualHost>

'AddHandler' and 'UspHandleIsm'

Now that you have specified your license key, we can start configuring the actual virtual host. This guide will focus on the parts related to setting up Unified Origin only. The more general settings such as ServerName, DocumentRoot and the configuration of your logs are not covered here.

To enable Unified Origin on a given virtual host, two directives are crucial: AddHandler and UspHandleIsm.

'AddHandler'

The AddHandler directive is used to ensure that files ending in .ism and .isml are going to be handled by the 'mod_smooth_streaming' module. If you want make the presentations available for progressive download then you also have to add the .mp4 extension. Adding this AddHandler will activate the module for the virtual host you are configuring:

AddHandler smooth-streaming.extensions .ism .isml

'UspHandleIsm'

The UspHandleIsm directive is used in combination with the <Location> directive to specify for which locations the smooth_streaming_module should be activated. 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 like so:

<Location />
  UspHandleIsm on
</Location>

Important

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

Cross domain access (CORS headers)

Another 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).

Additional settings for 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>

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)$">
  Require all denied
</LocationMatch>

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

Encoder specific settings

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 means that information about the OS-type and the compiled in modules will be send. On Debian / Ubuntu you can find and configure this directive in /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 directive in the Apache configuration and change it to 'On'.

KeepAlive On