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.

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

Changed in version 1.11.13: On Linux, the setup process was simplified through a few default configuration settings that are activated when enabling the mod_smooth_streaming module (i.e., Unified Origin), as detailed in the mod_smooth_streaming.conf file installed alongside mod_smooth_streaming.so:

  • Loads headers proxy proxy_http ssl socache_shmcb mod_unified_s3_auth modules as well, of which the latter is automatically installed as a dependency of the mod_smooth_streaming module and the others are part of a default Apache installation (with socache_shmcb being required as ssl now is installed by default as well)

  • Enables UspEnableSubreq for significant improvements when using remote storage backends, see Cloud Storage Proxy

  • Adds default configuration for Manifest Edit as detailed in Manifest Edit-related configuration, which does not impact setups that don't make use of Manifest Edit while reducing complexity for those that do

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 / Rocky Linux / RedHat

First, check which MPM model Apache is currently using:

sudo apachectl -M | sort

Note

You need to make sure that Apache has already started and running. Otherwise, you might get an error for the command above. Ie. AH00526: Syntax error on line 100 of /etc/httpd/conf.d/ssl.conf

If Apache is using the MPM model 'event', change it to 'worker' (or 'prefork') by opening /etc/httpd/conf.modules.d/00-mpm.conf in a text editor to uncomment the line for mpm_worker_module or mpm_prefork_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

Then save (please note 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, these changes will only take effect after a restart of Apache.

Enable 'mod_smooth_streaming'

If you have just installed the 'mod_smooth_streaming' module, you still need to enable it. Although unnecessary if you wish to check the module is installed you can do so like this (if smooth_streaming_module is not present in the printed list, the module is not enabled):

sudo apache2ctl -M | sort

Amazon Linux 2 / Rocky Linux / RedHat

To enable the module, open /etc/httpd/conf/httpd.conf in a text editor and add the following line:

LoadModule smooth_streaming_module modules/mod_smooth_streaming.so

Debian / Ubuntu

To enable the module:

sudo a2enmod mod_smooth_streaming

Basic Apache configuration on Windows

After you have installed Unified Origin as described in Installation on Windows, the three directories we will be focusing on for the configuration of Apache are:

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 add the following line to httpd.conf to instruct Apache to load mod_smooth_streaming.so:

LoadModule smooth_streaming_module modules/mod_smooth_streaming.so

Second, 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

Attention

The DocumentRoot for the default virtual host (httpd-vhosts.conf) needs to be updated before you can access any files.

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. 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 Rocky, you need to add the following to /etc/httpd/httpd.conf:

NameVirtualHost *:80

Specifying your license key

To specify your license key, add the UspLicenseKey directive to the file containing 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 <absolute/path/to/usp-license.key> should be replaced to point to the correct location):

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

<VirtualHost *:80>

  # Rest of config

</VirtualHost>

'UspHandleIsm'

Now that you have specified your license key, we can start configuring the actual virtual host. This guide will focus specifically on those parts related to setting up Unified Origin. 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 use 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

RequestReadTimeout

When using the webserver module for ingesting live streams, you need to take various timeout settings into account.

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>

Cache-Control

Cache-Control headers are only set for client manifests if they are dynamic (i.e., 'Live'). For certain use cases you may want to ensure that these headers are also set when a catch-up VOD clip is requested from a Live endpoint. To do this, you can use the following configuration, which adds a Cache-Control "max-age=2" header to client manifests only if no Cache-Control header was set at all

<LocationMatch ".*\.isml\/(.*\.mpd|.*\.m3u8|Manifest)$">
  Header setifempty Cache-Control "max-age=2"
</LocationMatch>

More detailed configuration

If you need to control the functionality in more detail you can use the regular expression LocationMatch to 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_smooth_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. The same applies to CMAF as source (cmfv, cmfa and cmft).

Prevent the download of server manifests

In order to protect your server manifests (VOD and Live) you have to disable access to ism and isml files.

# Block access to server manifests when the module is loaded
AddHandler smooth-streaming.extensions .ism .isml

# For when the module is not loaded
<IfModule !smooth_streaming_module>
  <LocationMatch "\.isml?$">
    Require all denied
  </LocationMatch>
</IfModule>

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