Controlling & Limiting the usage of your Wowza server application

"Only a life lived for others is a life worthwhile." – Albert Einstein

Controlling & Limiting the usage of your Wowza server application

INTRODUCTION


The Simple Usage Control module (ModuleSimpleUsageControl) for Wowza Streaming Engine™ media server software can be used to implement usage control on your server application by limiting various aspects of usage. This module was directly inspired by quite a few popular Wowza modules such as – wse-plugin-geoip, wse-plugin-limitpublishedstreambandwidth, wse-plugin-timeddisconnect and wse-plugin-limitstreamviewersSpecial thanks to Wowza engineers. Limiting usage can prove very useful in managing available server resources in an efficient manner. The module allows you to configure various types of limits on your application such as total publishers, total subscribers, publish time, subscribe time, and country(location) based limiting via [Maxmind GeoIP database](https://dev.maxmind.com/geoip?lang=en) or [IPWHOIS free api service](https://ipwhois.io/).

Contents


Prerequisites


  • Wowza Streaming Engine 4.8.x or later is required.
  • An account with Maxmind to use their GEO-IP web service or download the GeoLite2-Country binary database file (optional)
  • An account with IPWHOIS to use their free API service commercially (optional)

Installation


  1. Download the latest release of rtmpworld-wse-plugin-simpleusagecontrol  & rtmpworld-wse-utilities shared library archives.
  2. Extract the contents from the downloaded (zipped) packages.
  3. Rename extracted files lib/rtmpworld-wse-plugin-simpleusagecontrol-x.x.x.jar to lib/rtmpworld-wse-plugin-simpleusagecontrol.jar & rtmpworld-wse-utilities-x.x.x.jar to rtmpworld-wse-utilities.jar
  4. Then copy the lib/rtmpworld-wse-plugin-simpleusagecontrol.jar & rtmpworld-wse-utilities.jar file from the package to the lib folder in your Wowza Streaming Engine installation ([install-dir]/lib).
  5. Download the geoip2-x.x.x.jar and maxmind-db-x.x.x.jar from github and copy it to [install-dir]/lib
  6. Restart Wowza Streaming Engine.

NOTE: rtmpworld-wse-utilities shared library (rtmpworld-wse-utilities.jar) is a dependency for all our modules. It is not a module in itself. It simply contains resources that are used by our modules at runtime. If you are using multiple modules from us then you should copy this file just once into the lib folder of your Wowza Streaming Engine installation ([install-dir]/lib).

Configuration


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

NAMEDESCRIPTIONFULLY QUALIFIED CLASS NAME
ModuleSimpleUsageControl
Implements usage control on the server application by allowing limiting of various streaming aspects.
com.rtmpworld.server.wowza.plugins.ModuleSimpleUsageControl

Properties


After enabling the module, you can adjust the default settings by adding the following properties to your application. See Configure properties for details.

APPLICATION LEVEL PROPERTIES
PATHNAMETYPEVALUENOTES
/Root/ApplicationusagecontrolRestrictionsRulePath
StringFilesystem path to restrictions.json file that defines all the usage control rules. Sample JSON can be downloaded here.
/Root/ApplicationusagecontrolMaxmindDBPathStringFilesystem path to MaxMind binary database file.
/Root/Application
usagecontrolMaxmindAccountId
StringMaxmind accountId. this is required when you are using the MaxMind geoip2 web service. To use the web service you will need to configure the accountId as well as the license key.

/Root/Application
usagecontrolGeoApiLicenseKey
StringThe license key for using geo API. A license key is required whether you are using MaxMind web service or IPWhois API.
/Root/ApplicationusagecontrolSessionCacheDurationNumberSession cache is used to block HTTP and RTMP clients from reconnecting immediately after a rejection. The max duration for sessionCache block on clients in seconds. The default is 10 minutes.
/Root/Application
usagecontrolDebug
BooleanTrue/FalseToggles debug mode for the module for increased logging.
SERVER LEVEL PROPERTIES
PATHNAMETYPEVALUENOTES
/Root/ServerusagecontrolThreadPoolSizeInteger5The number of threads used to fetch geo-information data in seconds. (default: 5)
/Root/ServerusagecontrolThreadPoolTerminationTimeoutInteger5The maximum time (in seconds) to wait for pending/ongoing geo-ip requests before shutting down request executor.

Use Wowza Engine Manager interface to add & configure modules for your Wowza Streaming Engine instance.

Usage


The module allows you to configure multiple usage restrictions on your Wowza server application using a simple JSON configuration file – restrictions.json.


restrictions.json SAMPLE

{
	"enableRestrictions": true,
	"maxMegaBytesIn": 0,
	"maxMegaBytesOut": 0,
	"ingest": {
		"maxPublishBitrate": 1000,
		"maxPublishersCount": 2,
		"maxPublishTime": 0,
		"allowedFromGeo": ["IN"],
		"restrictFromGeo": []
	},
	"egress": {
		"maxSubscribers": 10,
		"maxSubscribersPerStream": 10,
		"maxPlaybackTime": 45,
		"allowedFromGeo": [],
		"restrictFromGeo": []
	}
}
ATTRIBUTE DEFINITIONS
PropertyDescription
maxMegaBytesInmaximum inwards bandwidth of the server application (in MB)
maxMegaBytesOutmaximum outwards bandwidth of the server application (in MB)
ingest.maxPublishBitratemax publisher stream bitrate
ingest.maxPublishersCountmaximum number of publishers
ingest.maxPublishTimemaximum stream publishing time (duration in seconds)
ingest.allowedFromGeocountries from where publishing is allowed
ingest.restrictFromGeocountries from where publishing is restricted
egress.maxSubscribersmaximum total number of subscribers
egress.maxSubscribersPerStreammaximum subscribers per stream
egress.maxPlaybackTimemaximum stream playback time (duration in seconds)
egress.allowedFromGeocountries from where playback is allowed
egress.restrictFromGeocountries from where playback is restricted

For Developers


UNDERSTANDING THE FEATURES

APPLICATION-LEVEL BANDWIDTH CONTROL


The maxBytesIn & maxBytesOut control the maximum inwards and outwards bandwidth limit for the application for which the module is configured. Once the application’s total used bandwidth for the session hits these limits it won’t allow ingest/egress activities until the application or server is restarted to clear the memory count of used bandwidth.

The values for maxBytesIn & maxBytesOut are to be specified in bytes (52428800  etc).

GEO-LOCATION CHECKING


The allowedFromGeo & restrictFromGeo attributes are arrays of country codes. When a client connects and attempts the publish/playback actions in the application, the geo-location check is invoked if the restrictions have been enabled application-wide. Based on whether MaxMind binary database is available or the web service, the application will use the client’s remote IP address to know its country code. This code will then be checked against the allowedFromGeo & restrictFromGeo arrays to determine whether the publish/playback action is to be allowed or not.

The values for allowedFromGeo & restrictFromGeo will be country codes like: ["US", IN"] (USA and India)

MAX SUBSCRIBERS


SimpleUsageControl offers two types of subscriber limiting. Firstly you can put a limit on total subscribers on the application itself using the attribute maxSubscribers and second, you can limit subscribers per stream using the attribute maxSubscribersPerStream. That auto implies that maxSubscribers cannot be less than maxSubscribersPerStream.

Max subscribers can be an numerical positive value such as 10, 20, 50 etc

CONFIGURATION FOR REALTIME GEO-INFORMATION

This module supports real-time geo-information fetching (IP to country) to implement geo-restrictions on clients. to facilitate this feature the module has three built-in geo-information providers that are mutually exclusive to each other.

MaxmindDBGeoInfoProvider


This provider uses Maxmind binary database to map IP to country. To enable it you need to configure the usagecontrolMaxmindDBPath property of the module to locate the full absolute path of the Maxmind geolite2 binary database file.

To use Maxmind GeoIP you will need the GeoLite2-Country binary database, and thus you need to have an account with Maxmind.com. Additionally, you need to download the dependencies (Jar files – maxmind-db and geoip2) required for the module to work with MaxMind java API.

MaxmindWebServiceGeoInfoProvider


This provider uses MaxMind WebService/API to get country info against an IP address. To enable it you need to configure the usagecontrolMaxmindAccountId & usagecontrolGeoApiLicenseKey properties of the module, where the former is your MaxMind account id and the latter is the API license key.

To use Maxmind GeoIP Webservice you will need a license key and the maxmind account id, and thus you need to have an account with Maxmind.com. Additionally, you need to download the dependencies (Jar files – maxmind-db and geoip2) required for the module to work with MaxMind java API.

IPWhoIsWebServiceGeoInfoProvider


This provider uses IPWHOIS’s free API to get country information from an IP address. To enable it you need to configure the usagecontrolGeoApiLicenseKey property of the module. the free version of the API does not require any license key and can serve up to 1000 requests per day. To go beyond this you will need a license key. When you are using the free API, specify the value for usagecontrolGeoApiLicenseKey as LICENSE KEY.

Known Issues


  • NA