Serving Static Files

Opencast comes with a central service for serving static content as well as providing capabilities like byte-range requests for seeking in larger media files. This service is used by almost all publications. The publish-enage, publish-oaipmh and publish-configurable operations are just a few examples of code relying on this.

The service itself acts just like a web server and will serve any file in a specific folder if no authentication is configured to be required. Note that most of the files generated by Opencast are intentionally named in a way which makes them extremely hard to guess so that even when authentication checks are disabled, the file names still work like a share link and no one can just browse all available files.

Usually, at least the following paths are delivered by this service:

Securing Static Files

The static file service has a plug-in mechanism which allows modules to claim specific patterns to protect its content. If this is enabled, access is denied to all files which are not claimed by such a plug-in. An example for a service providing protection is the search service which claims all /static/engage-player/… links and checks the access control lists published to Engage before allowing access.

The configuration options for requiring authentication can be found in the service's configuration file at etc/org.opencastproject.fsresources.StaticResourceServlet.cfg.

For some external software, like the ILIAS plugin and Tobira, it is required to set authentication.required to false as static files authorization is active by default.

An alternative method to this is Opencast's token based authorization system which allows (and requires) to defer all security checks to external systems.

Available Static File Authorization Plug-ins

Simple Configurable Static File Authorization

The configurable authorization plug-in allows to simply grant access to an arbitrary amount of pre-configured patterns. This can be used to easily allow access to a custom publication channel. By default, this allows access to OAI-PMH publications.

The configuration for this plug-in can be found in etc/org.opencastproject.fsresources.SimpleConfigurableStaticFileAuthorization.cfg.

Search Service / Engage Publication

The “engage” publication is the publication to media module and player. The publication usually includes an access control list which is checked by both user interfaces (really by the underlying search service). The search service contains a static file authorization plug-in which also checks the files used by those interfaces (preview images, videos, …) against the same access control lists, making sure that file links are not extracted and passed around.

The pattern protected by the search service is /static/engage-player/<media-package-id>/…

For performance reasons, access control lists are cached for one minute per user, meaning that there may be a short delay when changing access control.

Asset Manager (External API, Admin Interface, Internal)

The admin interface and external API have their own publication channels. Access to these resources is based on access control lists stored in the asset manager which therefore comes with a static file authorization plug-in.

The patterns to protect can be configured. By default, the asset manager static file authorization plug-in will protect the URL pattern /static/api/<media-package-id>/… and /static/internal/<media-package-id>/…

Performance Optimization

By default Opencast's static file service is reading files from the hard disk through its own code and then serving those files using the built-in Jetty HTTP server. This works perfectly fine, and is robust even on larger installations. Nevertheless, it is far from being the fastest option when it comes to serving static file content. Other projects, such as Nginx, have specialized in this and are much more performant.

That is why the static file service supports X-Accel to defer the file transfer to Nginx while keeping the authentication and authorization parts in Opencast. The configuration to activate this feature can be found in the service configuration file at etc/org.opencastproject.fsresources.StaticResourceServlet.cfg:

x.accel.redirect=/protected

Configuring a path in this option will make Opencast return a X-Accel-Redirect header for the requested static file prefixed by the configured value instead of serving the actual content.

This will be picked up by Nginx if it is used as reverse proxy and treated as an internal redirect to the actual files. Thus, for this to work, there needs to be a matching internal location configuration like this:

location /protected/ {
  internal;
  alias /srv/opencast/downloads/;
}