GeoIP Plugin for Wowza

Overview

The intent of this plugin is to provide a facility, with which it's possible to make advanced access rules based on the client's IP and Geolocation (GeoIP) data. The rules act as an application firewall, which allows or denies access to live and VOD streams based on your configuration.

The plugin should be compatible against Wowza 4.5.0+.

Installing the plugin

First off, copy the jar files into your WowzaStreamingEngine's lib/ folder. On Linux systems, the location for it is usually /usr/local/WowzaStreamingEngine/lib/.

You have to enable the GeoIP plugin for specific applications where you want to use it. You should add the following configuration into the Application.xml in every application that you want to enable it. The configuration should be added into the <Modules> section, just after the <Module>...</Module> declaration for logging.

<Module>
    <Name>geoip</Name>
    <Description>GeoIP</Description>
    <Class>com.titpetric.wse.module.GeoIP</Class>
</Module>

The WowzaStreamingEngine needs to be restarted to enable the module.

Plugin configuration

The plugin provides some configuration and reasonable default options. The configuration should be added into the <Properties>...</Properties> section of the Application.xml.

Most configuration options take effect only when a geoip.xml file isn't provided. A common scenario for using them is declaring a "safe" configuration in case of syntax errors in the geoip.xml file, or just to bypass the file completely.

GeolocationDefaultRestrict (Integer)

The option defines the behaviour of the GeoIP plugin, if no rules match. The default is not to restrict anything, allowing playback of requested assets.

Possible values
0 - don't restrict anything by default
1 - restrict everything by default

Default value: 0

GeolocationDefaultRestrictCountry (String)

If the xml configuration for the GeoIP plugin is missing or invalid, the GeoIP plugin will restrict to this country listed here.

Value	ISO 3166 Country Code

GeolocationConfigFile (String)

Value	The absolute filename for the GeoIP config XML

The value is expanded with the following variables:

${com.wowza.wms.AppHome} - Application home directory (test)
${com.wowza.wms.ConfigHome} - Configuration home directory (test)
${com.wowza.wms.context.VHost} - Virtual host name
${com.wowza.wms.context.VHostConfigHome} - Virtual host config directory
${com.wowza.wms.context.Application} - Application name
${com.wowza.wms.context.ApplicationInstance} - Application instance name

The property allows you to configure distinct GeoIP blocking rules for multiple VHosts or Applications.

Example value: ${com.wowza.wms.context.VHostConfigHome}/conf/geoip.xml

GeolocationPlaybackShutdown (Boolean)

This property sets the behaviour of the GeoIP plugin and what it does with the client, if the client fails the GeoIP location checks.

Value	Description
true	Shutdown stream if Client is not in a validated GeoIP territory
false	Rewrite stream to the clip defined in `GeolocationPlaybackFile`

Default value: true (shutdown stream)

GeolocationPlaybackFile (String)

Value	Path to the clip or stream which tells the user via video, why he can't access some of the sites content.

Only used if GeolocationPlaybackShutdown is set to false.

Example value: mp4:redirect.mp4

GeolocationDebug (Boolean)

Value	Description
true	Turn on debugging
false	Turn off debugging

Default value: false (debugging turned off)

GeoIPDatabase (string)

Value	The location of GeoIP.dat file

Default value: /usr/share/GeoIP/GeoIP.dat

The GeoLite City database should be used with the plugin. The database is downloadable on the MaxMind website (direct link). Unfortunately, the GeoLite Country database is not compatible with this plugin at this time, as it specifically requires data only available in the City database for some features.

Advanced rules for IP and GeoIP filtering

The behaviour of the plugin is controlled by a geoip.xml file, which is set using the GeolocationConfigFile configuration property (see above). Using the configuration in this xml file, most of the plugin Properties listed above are replaced.

This is an example geoip.xml which you can use for a starting point.

<?xml version="1.0" encoding="utf-8"?>
<geoip>
    <!-- mode: block|rewrite -->
    <mode>rewrite</mode>

    <!-- list rewrites, default doesn't have src attribute -->
    <rewrites>
        <rewrite app="live">sorry.sdp</rewrite>
        <rewrite app="vod">mp4:sorry.mp4</rewrite>
        <rewrite app="front">vod/mp4:sorry.mp4</rewrite>
    </rewrites>

    <locations>
        <!-- Location: path = stream name or folder (for vod), restrict = [all|none] -->
        <location path="sorry.sdp" restrict="none"/>
        <location path="sorry.mp4" restrict="none"/>
        <location path="(.+\.sdp|[0-9]+\.mp4)" type="regex" restrict="none">
            <except type="country">SI</except>
            <except type="country">AT</except>
            <except type="ip">127.0.0.1</except>
        </location>
        <location path="\_.+" type="regex" restrict="none">
            <except type="country">AT</except>
        </location>
    </locations>
</geoip>

The <mode> tag

The value of the <mode> tag specifies what the behaviour will be enforced, if a client is denied access based on rules specified below.

block - shuts down the stream,
rewrite - rewrites the requested stream to a placeholder video/stream

The <rewrites> tag

The <rewrites> tag declares individual <rewrite> rules.

The <rewrite> tag

Each <rewrite> rule has an app parameter, which is used for matching applications in which a request has been blocked. When the application matches, and <mode> is set to rewrite - the request will be rewritten, showing the user a different video than the one requested.

The usage for this is usually to provide some kind of notice to the user, that they are trying to view a video stream outside of allowed territories. This may happen due to licensing obligations for video files, or just as a policy where local streaming providers only service the local market.

The <locations> tag

The <locations> tag declares individual <location> rules.

The <location> tag

Each <location> tag is used for matching requests to video files and streams as they are coming in. The path parameter is matches against the requested stream. If the path matches, individual nested <except> blocks are processed.

Parameter	Value
path	The value of the path parameter depends on `type` It may be a literal value (the name of the video file or stream), or it may be a regular expression patern
type	omit/none, `regex`- uses `path`value as a regular expression
restrict	all - restrict all access, none - allow access

With the setting of the restrict parameter, it's possible to construct advanced rules, which operate on broader criteria - for example, you can block all countries except US (restrict all, except US), or you can allow all countries except US (restrict none, except US).

The system processes location entries only until the first entry whose path matches with the request. If no <except> entries are nested in the location, the locations default restrict parameter is enforced.

The <except> entry

The <except> entry is the workhorse of the GeoIP plugin. There are several types supported by the except notation which enable rich matching against a set of available data.

`type`value	Possible value	Description
ip	`10.13.37.1/24` `8.8.8.8` ...	IP, CIDR or netmask IP range notation, allowing filtering on IP level or on large IP blocks
country	`US` `AT` `SI`...	ISO 3166 Country Code
region	`AT,Wien` `AU,Victoria`...	region_codes.csv
city	`AT,Wien,Wien` `US,New York,New York City`...	...

It is a restriction of the region and city matchers to match all distinct location fragments. The reason for this is simple enough, there is a region named Victoria in Australia (AU) and in Trinidad and Tobago (TT). Without the information of the country code, we wouldn't have an accurate match against it. And weirdly enough, there are a few places on the planet named Amsterdam, London, and Moscow. In fact, there are more than 20 cities in the United States (US) named Moscow (source).