Upgrade to a New Version

It is important to understand the relationships between the different pieces of software and the correct procedures to take before deploying upgrades in your production environment.

Note

When using Linux, upgrade by accessing our repository via your package manager, as explained in the relevant section of our Linux installation instructions (i.e., Add repository on Alpine, Add repository on Rocky Linux, AlmaLinux, or Red Hat Enterprise Linux (RHEL) or Add repository on Ubuntu / Debian). When using Windows, a direct download is available, about which you can find more information in the Installation on Windows installation instructions.

Installation of packages

Part	Description
libfmp4	Library providing Unified's functionality
mp4split	Commandline driver
mod_smooth_streaming	Webserver module

mod_smooth_streaming is the name of the Unified Streaming webserver module, it uses a library (libfmp4) that is installed by mp4split, the packaging tool.

For this reason you should ensure that the installed versions always match.

You must for example not install a newer version of mod_smooth_streaming in an environment that has an older version of MP4split installed.

License

When deploying an upgrade it is possible a new license is required or it may be the case that a renewal has dictated the need for a new license.

Due to the way the license is loaded by the Webserver it's important to ensure the new license is being loaded from the correct file. When you are adding a new license check that you are not including older license files in your config's include paths.

Confirmation that your license is being loaded correctly is always logged to the Webserver's main error log. If you use tail or a text editor to examine this when the server is reloaded you will see it print a status message in the log file stating the license has been successfully loaded, if it has not been able to read it or there is an issue with the license itself this will also be logged. Once you have confirmed it is being loaded successfully and the license is indeed the correct one, you should try to access a manifest to further confirm the license and origin are continuing to provide the required license options.

Release notes

A full list of functionality that has been added in each release revision is kept here, you should be able to find the set of changes between your current release and the release you wish to upgrade to.

The release notes are made live when a new release is made public along with any additional documentation covering the changes or new features in the release.

Operating system differences

On Linux the mp4split package contains libfmp4 which is used by both the webserver module and unified_capture. On Windows unified_capture is a standalone executable.

Once the parity of the software components is confirmed you should proceed to install the upgrade versions in your staging environment.

Staging environment

Your staging environment should be as close to your production environment as possible. It is not advised to base a staging environment on a local machine and is preferable it be on a remote server which may connect to other production services and data, and the same assets and manifests that the production servers can access.

A typical workflow is as follows:

development --> staging --> production

A development setup for initial testing followed by a staging setup that closely mimics the production environment (see the next section).

Key functionality

It is important to ascertain what key functionality you are providing with the current production deployment. This could be many things, from DRM to TransDRM, EPG functionality, internally or on the playout side, specific configurations for certain devices.

Make sure you can copy or replicate all of this key functionality in your staging environment.

Carefully go through all the key functionality you are using the software to provide and check the release notes from the version you are currently running in production through to the version you are upgrading to. Has functionality that you provide changed, have new features been added? It might be that although the software is backwards compatible a DRM provider has changed their implementation and there is new documentation available.

Deployment considerations

The software is best installed using the package manager of the platform, so apt (or dpkg) on Debian based distributions or yum (or rpm) on RPM based distributions.

Before upgrading the software the webserver should be stopped.

In order to have the server's shared object caches update it's recommended to run the following command:

#!/bin/bash

sudo ldconfig

During the time the Webserver is offline the Live archive is not updated. This will cause discontinuities in the timeline. Missing parts of the archive can be re-added by POSTing the missing part from another origin which kept ingesting while the first server was updated.

Alternatively, the archive could be cleared completely (by removing all files) and the origin could be marked online again (and for instance added to the loadbalancer pool) once the archive is full again.

Caching

Although we make efforts to avoid it, in some cases an upgrade may lead to incompatibilities between content produced by different versions due to changes or bug fixes.

For example, when upgrading from a version older than 1.9.5 to 1.9.5+ DASH manifests using Segment Timeline may differ due to rescaling and rounding issues that were fixed. This requires cache invalidation of affected manifests to prevent clients requesting segments with incorrect URLs.

Note that cache purging also might apply when updating players for instance. If the cache contains older versions of manifests/media and the updated player mandates caches need to be purged for changes to take effect.

Due to the nature of these types of changes they may or may not affect you depending on exactly how your content is produced, so we always recommend testing and comparing the output of the old and new version.

See also the notes in Cache invalidation/purge in the Origin shield cache best practice.