Examples: Geo IP

This package contains an example plugin for Wowza Media Server that enables geographic locking functionality for RTMP, HTTP, and RTSP connections. It works with downloadable IP geolocation (GeoIP) country databases from MaxMind, Inc. The GeoIP Country database is available for one-time purchase or paid subscription. A less-accurate of the GeoIP Country database (the GeoLite Country database) is available free-of-charge. Developers can download an open-source LGPL-licensed GeoIP Java library (GeoIPJava-latest.zip) and integrate it with this package for custom implementations.

The package implementation consists of two main modules. A server listener and an application module, both of which must be configured for the geographic locking functionality to work correctly.

Note: Wowza Media Server® 3.5 or later is required.

To install

Install Wowza Media Server.

Copy the files lib/wms-plugin-geoip.jar and lib/maxmindgeoip.jar from this package to the Wowza Media Server installation folder [install-dir]/lib/.

Configuration

The server listener module ServerListenerGeographicSelector loads a MaxMind IP geolocation database and makes it available to multiple Wowza Media Server applications.

To enable the server listener, open the [install-dir]/conf/Server.xml file in a text editor and add the following to the <ServerListeners> container in the file:

<ServerListener>
	<BaseClass>com.wowza.wms.plugin.geoip.ServerListenerGeographicSelector</BaseClass>
</ServerListener>

The server listener loads the MaxMind IP geolocation database file named GeoIP.dat. By default, this file is located in [install-dir]/conf on the Wowza Media Server. If you store the GeoIP.dat in a different location on the server, you must specify the full path and file name of the non-default location in the server configuration. Open the [install-dir]/conf/Server.xml file in a text editor and add the following <Property> to the <Properties> container at the end of the file:

<Property>
	<Name>geoipDatabaseLocation</Name>
	<Value>/usr/local/WowzaMediaServer/lib/GeoIP.dat</Value>
</Property>

The application module ModuleGeographicSelection uses the server listener to access the MaxMind IP geolocation database. In doing so, it enables multiple applications to access the database without the need to load it multiple times.

To enable an individual application to access the IP geolocation database, open the [install-dir]/conf/[app-name]/Application.xml file in a text editor and add the following module to the <Modules> container in the file:

<Module>
	<Name>ModuleGeoIPLock</Name>
	<Description>ModuleGeoIPLock</Description>
	<Class>com.wowza.wms.plugin.geoip.ModuleGeographicSelection</Class>
</Module>

The ModuleGeoIPLock geographic locking module allows IP addresses from a defined set of countries to connect. You can bypass the geographic lock for specific encoders and IP addresses by adding the following properties to the <Properties> container at the end of the [install-dir]/conf/[app-name]/Application.xml file.

Encoder whitelisting

Specifies encoder names that will bypass the geographic lock.

<Property>
	<Name>geoipAllowEncoder</Name>
	<Value>FM,Wirecast</Value>
</Property>

IP whitelisting

Specifies IP addresses that will bypass the geographic lock.

<Property>
	<Name>geoipAllowIP</Name>
	<Value>10.1.1.1,10.1.1.201,8.8.8.8,192.168/Value>
</Property>

Note: You can specify a partial IP address and any IP address that starts with that range is allowed to connect.

Geographic country list

Specifies that IP addresses in certain countries (specified by ISO 3166 code) bypass the geographic lock:

<Property>
	<Name>geoipCountries</Name>
	<Value>GB,FR,US</Value>
</Property>

Geographic country include/exclude

The Geographic Locking module allows IP address in countries that are specified by the geoipCountries properties list to connect. To exclude IP addresses in that list of countries from bypassing the geographic lock, add the following property to the [install-dir]/conf/[app-name]/Application.xml file

<Property>
	<Name>geoipCountriesInclude</Name>
	<Value>false</Value>
	<Type>Boolean</Type>
</Property>

Lock By Default

The Geographic Locking module blocks connections by default until the GeoIP Database is loaded. This behavor can be changed to accept connections by addding the following property to the [install-dir]/conf/[app-name]/Application.xml file

<Property>
	<Name>geoipBlockByDefault</Name>
	<Value>false</Value>
	<Type>Boolean</Type>
</Property>

Additional Logging

The Geographic Locking module allows the user to enable additional log messaging to facility debugging by addding the following property to the [install-dir]/conf/[app-name]/Application.xml file

<Property>
	<Name>geoipDebug</Name>
	<Value>true</Value>
	<Type>Boolean</Type>
</Property>

Running Wowza Media Server

After you start Wowza Media Server, you'll see the following message if GeoIP.dat was loaded successfully:

ServerListenerGeographicSelector.loadGeoIPDatabase: Loaded requested database from: <location of GeoIP.dat>

Or the following message if the file couldn't be loaded:

ServerListenerGeographicSelector.loadGeoIPDatabase: Could not load requested database; reason <reason> from location <location checked>

Wowza Media Server Examples: GeoIP

To install

Configuration

Running Wowza Media Server