Table of Contents



See OS Specific Installation for installation instructions.


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

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

When using Apache Lounge the directory structure will look like this:

Directory Use
C:\Apache24\modules Location of mod_smooth_streaming.so
C:\Apache24\conf Location of httpd.conf and the license key

To load the module and license key, add the following two lines to your httpd.conf:

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

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

The AddHandler and UspHandleIsm keyword (discussed below) should be added as well, for instance in httpd-vhosts.conf.


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.

See the Apache License Key section for the location of the license key.

MPM model

The default MPM model in Apache 2.4 is most likely 'event' on your Linux platform. 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 this for instance can be done with sudo a2dismod mpm_event followed by sudo a2enmod mpm_worker.

Module loading

On Debian/Ubuntu this is done as follows:

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

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

On CentOS:

LoadModule smooth_streaming_module modules/mod_smooth_streaming.so

LoadModule can be set in the server config: /etc/httpd/httpd.conf.

To allow for multiple virtual host on CentOS the following should be added in the server config, /etc/httpd/httpd.conf:

NameVirtualHost *:80

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.

To enable the module for a virtual host the following should be used:

AddHandler smooth-streaming.extensions .ism .isml

The last step is to enable the 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.


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

<Location />
  UspHandleIsm on

If you need more fine grained control, please see the 'More detailed configuration' below.

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

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


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

Enable just-in-time packaging for MP4:

<LocationMatch "\.mp4/">
  UspHandleIsm on

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

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

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

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


The options apply to the VirtualHost directive.

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).
IsmProxyPass Pass .ism to proxy (a virtual path and URL), see HTTP Proxy.
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).
S3SecretKey The AWS secret key (see Using webserver directives for S3 authentication).
S3AccessKey The AWS access key (see Using webserver directives for S3 authentication).

The directive UspEnableMMAP controls whether the webserver module uses imemory 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

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

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