Enable geographic locking with a Wowza Streaming Engine server listener and Java module

GeoIP AddOn enables IP addresses to be checked against a IP geolocation (GeoIP) lookup service or database so that you can lock RTMP, HTTP, and RTSP connections to Wowza Streaming Engine™ from IP addresses in specified countries. The AddOn works with GeoIP2 Precision Web Services or GeoIP2  Country databases from MaxMind, Inc.

Prerequisites


  • Wowza Streaming Engine™ 4.7.5 or later is required.
  • Either a paid subscription to GeoIP2 Precision Web Services or a downloaded database is required. The GeoIP2 Country database is available for a one-time purchase or paid subscription. A less accurate version of the GeoIP Country database (the GeoLite2 country database) is available free-of-charge. The ASN and city-level databases will not work with this module.
  • The following jar files from the Maxmind GeoIP2 GitHub releases page are required:
    • geoip2-x.xx.x.jar
    • maxmind-db-x.x.x.jar
  • Download the latest geoip2-x.xx.x-with-dependancies.zip file, unzip it, and copy the required jar files to your [install-dir]/lib/ folder. The rest of the dependencies are either already included in the Wowza Streaming Engine core files or are not required for the module to work.
Note: Version 2.12.0 or later of the MaxMind GeoIP2 files are required. The Dynamic Load Balancing AddOn package includes older versions of the MaxMind files that are not compatible with the GeoIP module. If the Load Balancer is installed, you must remove the MaxMind files provided with the Load Balancer before installing and configuring the GeoIP AddOn.

Installation


  1. Download the GeoIP AddOn package: wse-plugin-geoip.zip.
  2. Extract the contents from the downloaded (zipped) package, and then copy the lib/wse-plugin-geoip.jar file from the package to the lib folder in your Wowza Streaming Engine installation ([install-dir]/lib).
  3. Restart Wowza Streaming Engine.

Configuration


The AddOn package includes a server listener and an application module. You must configure both for the IP geolocation functionality to work correctly. The server listener is required to handle the database and web service connections and the caching of lookups. The module is configured for each application that requires it.

Server listener configuration

To enable the server listener, add the following server listener definition to your server in Wowza Streaming Engine Manager. See Configure server listeners for details.

Base Class
com.wowza.wms.plugin.geoip.ServerListenerGeoIp

The following properties can be set for the server listener. See Configure properties for details.

Path
Name
Type
Value
Notes
/Root/Server geoIpAccountId integer 12345 Precision web services account ID. Default is not set.
/Root/Server geoIpLicenseKey string xyz123 Precision web services license key. Default is not set.
/Root/Server geoIpDatabasePath string ${com.wowza.wms.ConfigHome}/conf/GeoLite2-Country.mmdb Path to GeoIP2 country database. Default is ${com.wowza.wms.ConfigHome}/conf/GeoIP2-Country.mmdb.

If credentials are set for the web service then this will be used instead of the local database.

Application module

To enable the module, add the following module definition to your application configuration. See Configure modules for details.

Name
Description
Fully Qualified Class Name
ModuleGeoIp Uses GeoIP lookups to control access. com.wowza.wms.plugin.geoip.ModuleGeoIp

After enabling the module, you can adjust the default settings by setting the following properties at the application level. See Configure properties for details.

Path Name Value Type Notes
Root/Application geoIpAllowedEncoders Wirecast, FME, FMLE string Encoder IDs that will not require a geoIP lookup. Default is the same as for Source Security.
Root/Application geoIpAllowedIps 127.0.0.1,192.168.1.* string IP addresses that won't trigger a geoIP lookup. A wildcard can be used. Default is not set.
Root/Application geoIpCountries US,GB string 2-letter ISO country codes to look for a match. Default is not set.
Root/Application geoIpMatchAllow true Boolean Blocks connections from specific countries. When set to false, matching country codes in the list will not be allowed to connect. Default is true.
Root/Application geoIpDebugLog true Boolean Set to true to enable extra debug logging. Default is false.

Usage

When a client/player makes a request to the server, a geoIP lookup is performed to determine if the connection is allowed. The ISO country code for the connecting IP address is checked against the list of country codes and the connection is allowed or blocked, depending on the configuration of the geoIpMatchAllow property. The default configuration is to only allow connections if a match can be found. To allow non-matching and block matching connections, set geoIpMatchAllow to false.

For developers


Get the source code on GitHub.