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-limitstreamviewers – Special 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
Installation
- Download the latest release of rtmpworld-wse-plugin-simpleusagecontrol & rtmpworld-wse-utilities shared library archives.
- Extract the contents from the downloaded (zipped) packages.
- 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
- 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).
- Download the geoip2-x.x.x.jar and maxmind-db-x.x.x.jar from github and copy it to [install-dir]/lib
- 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.
| NAME | DESCRIPTION | FULLY 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
| PATH | NAME | TYPE | VALUE | NOTES |
| /Root/Application | usagecontrolRestrictionsRulePath | String | Filesystem path to restrictions.json file that defines all the usage control rules. Sample JSON can be downloaded here. | |
| /Root/Application | usagecontrolMaxmindDBPath | String | Filesystem path to MaxMind binary database file. | |
| /Root/Application | usagecontrolMaxmindAccountId | String | Maxmind 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 | String | The license key for using geo API. A license key is required whether you are using MaxMind web service or IPWhois API. | |
| /Root/Application | usagecontrolSessionCacheDuration | Number | Session 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 | Boolean | True/False | Toggles debug mode for the module for increased logging. |
SERVER LEVEL PROPERTIES
| PATH | NAME | TYPE | VALUE | NOTES |
| /Root/Server | usagecontrolThreadPoolSize | Integer | 5 | The number of threads used to fetch geo-information data in seconds. (default: 5) |
| /Root/Server | usagecontrolThreadPoolTerminationTimeout | Integer | 5 | The 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
| Property | Description |
| maxMegaBytesIn | maximum inwards bandwidth of the server application (in MB) |
| maxMegaBytesOut | maximum outwards bandwidth of the server application (in MB) |
| ingest.maxPublishBitrate | max publisher stream bitrate |
| ingest.maxPublishersCount | maximum number of publishers |
| ingest.maxPublishTime | maximum stream publishing time (duration in seconds) |
| ingest.allowedFromGeo | countries from where publishing is allowed |
| ingest.restrictFromGeo | countries from where publishing is restricted |
| egress.maxSubscribers | maximum total number of subscribers |
| egress.maxSubscribersPerStream | maximum subscribers per stream |
| egress.maxPlaybackTime | maximum stream playback time (duration in seconds) |
| egress.allowedFromGeo | countries from where playback is allowed |
| egress.restrictFromGeo | countries from where playback is restricted |
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