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
- Download the GeoIP AddOn package: wse-plugin-geoip.zip.
- 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).
- 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.
