Wrench Configuration Reference

Installation Guide

Here is a step-by-step installation guide for Wrench if you prefer screenshots to manuals.

To install Wrench module into your Wowza Streaming Engine server, you need to copy the downloaded single wrench-yyyy.mm.dd.jar file into the lib directory of your Wowza installation.

You also need to copy the appropriate JDBC driver jar of your database file to the same lib directory. For a brief summary of the most popular JDBC drivers, please take a look at the FAQ section

Once installed, Wrench is ready to be loaded into any of your Wowza applications. If you want to enable Wrench for a particular application on your server, put the below configuration under that application's conf/myapplication/Application.xml file.

<!-- Make sure Wrench is the last configured module -->
<Module>
  <Name>Wrench module</Name>
  <Description>A module for user authentication and much more</Description>
  <Class>com.streamtoolbox.Wrench</Class>
</Module>

Wrench needs Java 8. (Since 2016.01.01. previously it worked with Java 7) The Java version used by Wowza is logged upon startup. Wrench won't get loaded if you are using Java 6 or 7.

Note: previous versions were packaged under com.wowzatoolbox, but this has been changed starting with version 2015.03.26.

Check installation

When you start Wowza and your application is loaded (e.g. publisher or first player connects), you should see this in the log file:

Starting Wrench yyyy.mm.dd, licensed to ...
Using database url ..., user ....
...
Started Wrench UI on http://localhost:4567/wrench/login

If you see this error message:

Module class not found or could not be loaded. Check [install-dir]/conf/live/Application.xml to be sure all Modules/Module/Class paths are correct: name:Wrench class:com.streamtoolbox.Wrench

That means that you did not copy the jar files to the right place under lib, or Wowza has no read permission on that file.

Wrench is not compatible with ModuleCoreSecurity's securityPublishRequirePassword feature. If used together, you might experience that publishers can't publish to your application. Please make sure that this is disabled in your configuration.

Reference of Application Properties

Here you can find the reference of all the settings that you can apply to Wowza Wrench by editing your Wowza application's Application.xml file. These properties have to go into the <Properties> section of your file as follows:

<?xml version="1.0" encoding="UTF-8"?>
<Root version="1">
 <Application>
  <Name>live</Name>
  ...
  <Properties>
 <Property>
   <Name></Name>
   <Value></Value>
 </Property>
  </Properties>
</Root>

Database Connection Settings

These are the important settings that control how Wowza Wrench connects to the underlying DB. This database is used for all SQL operations, there is no way to hit different databases for the different queries (at the moment). Wrench uses standard JDBC connection, so you can set various connection properties by putting them into the connection URL.

The database driver class has to be on Wowza's classpath, typically you can achieve this by copying the JDBC driver jar to the lib directory of Wowza. The JDBC driver for every major database can be found fairly easily with Google, where you can look up the exact name of the driver class you need to use.

There is a way to use Wrench without database, in that case setting wrench.db.driver to empty string will disable some of the features that don't make sense without database connection, but the webservice based features still remain.

Property Description Default
wrench.db.driver The name of the JDBC driver class. The default is that of MySQL, but if you don't want to use any database features, you need to set in explicitly to empty string to go into no-database mode. com.mysql.jdbc.Driver
wrench.db.url The JDBC url to your database jdbc:mysql://localhost:3306
wrench.db.user The username to connect to the db root
wrench.db.pass The password to connect to the db empty string

Database Connection Pool Settings

Due to the heavy usage of the backing database, Wrench uses Tomcat Pool to pool database connections. The current release lets you set some of the most typical settings of Tomcat Pool.`

Property Description Default
wrench.dbcp.initial.size Initial number of DB connections opened 1
wrench.dbcp.max.size The maximum size of the connection pool 1
wrench.dbcp.max.wait The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception, or -1 to wait indefinitely. -1
wrench.dbcp.test.on.borrow Set to true if you want DBCP to test connections before giving them to Wrench. This prevents client errors that occur if the DB closes a connection in the pool. The drawback is the increased DB load. false
wrench.dbcp.test.sql The SQL query executed to validate connections borrowed from the pool before using them. Use something easy, like select 1 from wtb_tokens

Token Settings

The token in this context is the one-time-password that is generated by your website/webapplication and is placed into the database together with the information about the user who got the token. This records enables Wowza Wrench to verify player connections and associate Wowza stream players (client in their terminology) with your users.

Property Description Default
wrench.encoder.token The hardcoded token that is used by your encoders, e.g. your Flash Media Live Encoder (FMLE) or ffmpeg to push the stream. This allows them to pass through Wrench's authentication and authorization. This is obviously not the only way you need to secure your publishers. Use IP filtering and all the other settings that Wowza itself offers you to restrict your sources. This setting has no default for security reasons, so it is mandatory to set your own. If you don't set this, Wrench will refuse your publisher unless that has a valid generated token too.
wrench.token.url.parameter The GET parameter in the connection URLs that carry the tokens. E.g. http://myserver/myapp/mystream?t=abc123 t
wrench.token.resolver.sql The query which should return the username and optionally the IP address and the token generation timestamp for a given token. The substituted parameter is :hashedtoken. Expected to return the username in column username (this is mandatory), the IP address in column ip (optional), the token's generation timestamp in column timestamp (needed only if token expiration check is enabled, the type of the client (i.e. encoder or player) in column encoder with boolean datatype or string true/false Since 2016.10.13. you can optionally return a numeric column bitratelimit which is the maximum allowed bitrate for the client. E.g. select user as username, ip, timestamp from wtb_tokens where token=:hashedtoken
wrench.token.resolver.url (Since 2015.05.01) The URL of the webservice responsible for determining the username and token generation timestamp and ip for a given token. This config parameter excludes the usage of wrench.token.resolver.sql mutually. The message sent to the webservice is: {"applicationName":"live","applicationInstance":"_default_","token":"foobar"}. The expected response format is: {"username":"john","timestamp (optional)": 1430484962, "encoder (optional)": true, "ip (optional)": "192.168.1.1", "bitrateLimit (optional)": 100000}. Only the username field is mandatory.
wrench.token.hashing The hashing algorithm that is used for storing the generated tokens. For security reasons it is not wise to store raw tokens, you should only store their hashes. Possible values are: md5,sha512 and plain md5
wrench.token.invalidate.sql A SQL query that is executed right after the token has been resolved. Substituted parameter is :hashedtoken and :username. This can be used to mark the token as used, so no further resolve attempts can use it again. Example: delete from wtb_tokens where token=:hashedtoken

Token Checking Mechanism

An overview of the authentication mechanism can be found here.

Possible checks that you can switch on are:

  • IP checking (with bypass list option)
  • Token expiration checking
  • Duplicate player checking (with configurable limit)
  • Http-Referer header black and whitelisting
  • User-Agent based black and whitelisting
  • External webservice invocation

IP checking requires that your token resolver query (wrench.token.resolver.sql) returns the IP address associated to the token. You have to make sure that you save it when you put the token into the database. When the token is resolved, Wrench checks that the IP address originally associated with the token is the same (simple string comparison happens) as the IP address of the client connecting to Wowza. This can help you to prevent users from transferring the URL with the token to an other user. IP address can be taken from a configured HTTP header wrench.ip.override.http.header if the server sits behind a proxy.

External webservice invocation allows you to involve an existing external webservice into the decision mechanism. Wrench can send a HTTP POST to the specified URL with a JSON body containing the name of the application, stream, user and the connection request is processed based on the response. See the technical details in the table.

Http-Referer and User-Agent headers are optionally sent by the players, and generally should not be trusted. Many players allow the user to set any arbitrary header to be sent. If the headers are missing, they are considered to be empty strings when the checks are performed.

Property Description Default
wrench.token.ip.check If set to true, the connection is only accepted if the client's IP address matches the one bound to the token. The expected IP address has to be returned in the ip column from the token resolver query false
wrench.token.expiry.sec The number of seconds in which a token expires. Expired tokens are not accepted. The token's generation timestamp has to be returned by the token resolver query in the timestamp column. This column can be either of number type, in this case it is assumed to be a Unix timestamp. If it is a date-like datatype, it is converted to Unix timestamp internally assuming the timezone of the JVM. 0 that means no expiry checking
wrench.duplicate.check If set to true, all connections are only accepted if there is no active player with the same username. Please note that upon ungraceful disconnection of the players, it might take a while for Wowza to notice the disconnection. This is controlled by the VHost's idleDisconnectTimeout setting. false
wrench.duplicate.limit Controls the maximum allowed concurrent sessions per user. Works only if duplicate checking is on. 1
wrench.duplicate.drop.other If switched on Wrench, given you have a limit of n concurrent players, when the n+1 th player connects, the connection is accepted, but a randomly picked other used is going to be dropped. false
wrench.duplicate.check.sql (Since 2015.03.26.) Optional. When specified Wrench will use this query to check concurrent players instead of using the in-memory list of current players. This feature comes handy when you want to check concurrent players across a set of edge servers. The query must return an integer telling Wrench the number of current players. You need to use the wrench.connect.accept.sql query to populate the list of players in the database, and use the wrench.disconnect.log.time.sql to remove entries. The drop feature is not working if the checking mode is SQL based. Parameters: :username select count(id) from wtb_duplicates where username=:username
wrench.duplicate.check.mode Controls the attribute which is checked when duplicates are searched. The default value is 'username', that means two sessions with the same resolved username are assumed the same. This is the most natural, however in some cases people want the 'token' to be the base of the checking, not the username. Default:username
wrench.user.agent.blacklist Specifies the User-Agent header (or Flashver in case of RTMP clients) blacklist regular expression Default: none. E.g. .*VLC.*
wrench.user.agent.whitelist Specifies the regular expression that each client's User-Agent header (or Flashver in case of RTMP) has to match none
wrench.http.autoaccept.ticket.count The number of subsequent connections made from the same IP with the same token that are accepted. This is needed when the website contains a direct link to the stream and the browser and the media player application both connect, but we don't want to count them as separate connections 3
wrench.http.autoaccept.ticket.timeout The length of the time window in which the above mentioned subsequent connections are not counted as separate ones. 15
wrench.http.referrer.blacklist Specifies the Http-Referrer header blacklist regular expression none
wrench.http.referrer.whitelist Specifies the regular expression that each client's Http-Referer header has to match none
wrench.rtp.check.enable If disabled Wrech won't react to RTP session creation and destroy events (onRTPSessionCreate and onRTPSessionDestroy). This feature can be used for RTSP IP camera sources, where the camera is not able to pass even a hardcoded token for Wrench. You'll still have all features for RTMP and HTTP based players. true
wrench.http.streamer.request.check.enable (Since 2015.01.23) Enables an extra check on all incoming HTTP queries, which is effective against direct chunklist access attempts. This feature only works on Wowza 4.1.x and above false
wrench.bypass.ip (Since 2015.02.14) You can define a comma separated list of IP addresses, which go to a whitelist. Any connection, encoder or client is accepted from these addresses. This can be used in case of hardware encoders that don't support query parameter sending in the URL.
wrench.bypass.publish.allowed (Since 2015.07.24) If enabled, then connections from the configured bypass IP addresses are always allowed to publish, no authorization is made via webservice or SQL. This is a convenience property for these cases. false
wrench.bypass.play.allowed (Since 2015.07.24) If enabled, then connections from the configured bypass IP addresses are always allowed to play a stream, no authorization is made via webservice or SQL. This is a convenience property for these cases. false
wrench.force.secure.transport (Since 2015.05.01) When enabled, only HTTPS and RTMPS connections will be accepted, non-secure transports will be refused. false
wrench.publish.encoder.flag.check (Since 2015.07.24) When enabled, this makes Wrench more strict about which clients are allowed to publish a stream. The token resolution SQL/webservice can optionally return an encoder flag, that tells Wrench the role of the client. If this checking is on, then only those clients are allowed to publish, who have this flag set to true. By default Wrench is unaware of this role and allows publishing for all clients. false
wrench.ip.override.http.header (Since 2016.10.13) The case insensitive name of the HTTP header which Wrench can assume to contain the IP address if the server is behind a proxy, e.g. X-Forwarded-For.
wrench.auth.failed.video.http.url (Since 2016.10.13) The URL of the video where the HTTP based players are redirected to if authorization fails
wrench.auth.failed.video.rtmp.url (Since 2016.10.13) The URL of the video where the RTMP based players are redirected to if authorization fails

Client Lifecycle Hooks

These SQL and webservice hooks allow you to precisely log user events in your system. If wrench.publish.http.url is set, the lifecycle events are published as HTTP POST messages with JSON payload to your webservice.

  1. Token resolution takes place first (via SQL or webservice call) (unless the connection comes from bypassed IP or using special token for encoders)
  2. Connection authorization (wrench.connect.authorization.sql)
  3. Connection accepted (wrench.connect.accept.sql)
  4. Duplicate player dropped (wrench.duplicate.drop.sql) if duplicate checking is on and a drop happens
  5. Publish authorization (wrench.publish.authorization.sql) if the connected user wants to publish something
  6. Disconnect (wrench.disconnect.log.time.sql) when the client disconnects. This happens immediately in case of RTMP protocol, and with a certain delay in case of HTTP protocol.
Property Description
wrench.disconnect.log.time.sql SQL query that is executed when any client disconnects. Can be used for simple audit purposes. Parameters are: :username, :session, :stream and :elapsedtime, this one is of type double, containing the seconds the player was connected
wrench.connect.authorization.sql Optional. If set, it is executed whenever a user successfully passed the token check. If the query returns at least one row, the authorization is successful, otherwise the connection is refused. Parameter: :username, :stream, :encoder. encoder is either true or false depending on what the wrench.token.resolver.sql's result set contains in the encoder column
wrench.connect.authorization.url (Since 2015.02.14) If set, this enables an external webservice HTTP POST upon each incoming connection. The body of the message is in JSON format: {"streamName": "mystream", "userName":"john", "token":"54ddec75e2294", "applicationName":"live", "applicationInstance":"_definst_"}. The expected result is HTTP 200 with a JSON content: {"result": "allow/deny"}. The connection is processed depending on the response. If any communication error occurs, or non HTTP 200 response is received, the result is defined by the ..default.result property.
wrench.connect.authorization.url.default.result (Since 2015.02.14.) The assumed authorization outcome result in case of any communication error, non-parseable JSON response or any HTTP response other than 200. By default it is false
wrench.publish.authorization.sql Optional. If set, it is executed whenever an RTMP or RTP client starts publishing a stream. If it returns zero rows, the publishing is denied, otherwise publishing is allowed. Parameter: :username, :stream
wrench.connect.accept.sql (Since 2014.11.05) Optional. If set, it is executed whenever a client successfully connected. Parameter: :username, :token, :hashedtoken, :ip
wrench.publish.http.url (Since 2014.11.05) An arbitrary URL where Wrench sends HTTP POST messages in JSON format when stream events occur. Events are: Publish, Unpublish, Pause, Start, Play, Stop, PauseRaw. The format of the JSON message is: {stream: "streamname", user: "username", event: "eventname"}. This feature can be used to sync external system with these events. The username is the username of the connecting encoder, which assumes that in this scenario encoders won't user encodersecret, but will connect as regular users with dynamic token.
wrench.duplicate.drop.sql (Since 2015.01.23) Optional. If set, it is executed whenever a client is dropped due to the duplicate checking mechanism, which needs to be enabled. Parameter: :username

Pay-per-minute and pay-per-view configuration

Wowza Wrench enables you to accurately measure stream consumption for accounting or statistical purposes. The pay-per-view feature allows you to count how many times each user started watching your stream (allowing a small non-counted grace period). The pay-per-minute SQL hooks make allow you to measure the time spent watching the stream.

The following SQL queries all have to be tailored to your DB schema and the syntax of your RDBMS. The possible properties that you can use in the queries are:

  • :username - the username, resolved by Wrench based on the passed token
  • :application - the name of the Wowza application
  • :elapsedtime - the number of elapsed seconds (also fractions, as returned by client.getElapsedTime().getTimeSeconds())
  • :session - a unique identifier of the user's session generated by hashing the username and the connection time
Property Description Example
wrench.monitor.period The period of the monitor job which performs all PPV and PPM data capture. This determines the minimum resolution in time of your captured data. Default: 60
wrench.ppv.grace.period Clients disconnecting before this period are not captured by the pay-per-view monitor, so effectively their connection does not count Default: 5 sec
wrench.ppv.insert.sql This query is executed whenever the wrench.ppv.update.sql did not update any rows in the database. insert into wtb_views (user, count) values (:username, 1)
wrench.ppv.update.sql This is executed whenever a new user's connection time exceeds the grace period. update wtb_views set count = count + 1 where user=:username
wrench.ppm.update.sql This query is executed for all users each time the monitor job is running. This should be used to update the playing time for each client. The session parameter is a hash generated from the username and the connect time to allow you storing total times of consequtive sessions in the same table. update wtb_minutes set total=:elapsedtime where user=:username and application=:application and session=:session
wrench.ppm.insert.sql This query is executed whenever the wrench.ppm.update.sql does not affect any row in the database. Use it to insert new records into your table. insert into wtb_minutes (user, application, total, session) values (:username, :application,0,:session)
wrench.ppm.disconnect.sql If set, this query is executed periodically on each monitor run. If the query returns 0 rows, the client is immediately dropped. This can be used to dynamically check its PPM balance and drop users if their balance goes down
wrench.ppm.update.publish (Since 2015.03.26) If set to true (default is false), the PPM engine will POST JSON messages to the configured wrench.publish.http.url. The message format is as follows: {"users": [{"username": "john", "duration":360.578, "session":""}], "event":"PpmUpdate", "timestamp":"2015-03-16 21:40:28.259"}. The message is sent asynchronously.

Dynamic public mode switching

Wowza Wrench can temporarily disable its authorization and authentication process and allow access to your streams publicly. This mode can be useful if you are broadcasting a live event and want to make a part of it public, such as the opening ceremony of a football match. Wrench knows which clients came for free and which ones were verified and unverified. While in public mode, users with proper token will be verified and not dropped when you switch back to secured mode. The switching mechanism can be as simple as creating and deleting a particular file on your file system, or returning or not returning rows from an arbitrary SQL query.

Property Description Default
wrench.switchable.public Set to true to enable dynamically switchable public mode feature false
wrench.switchable.public.check.period The period time of mode checking in seconds 10
wrench.switchable.public.check.mode The switch mechanism you want to use. Can be file or sql (case insensitive
wrench.switchable.public.check.file The name of the file used to determine current mode if check mode is set to file. If the file exists, the mode is assumed to be public, secured otherwise
wrench.switchable.public.check.sql The SQL query used to determine current mode if check mode is set to sql. If the query returns empty result set, the mode is assumed to be secured, if any rows are returned, then public. You can use the following parameters in the query: :vhost, :application, :appinstance

When going from public mode to secured, you should see this in the logs (INFO level):

INFO Switching from public mode to secured mode, dropping all unverified clients
...
INFO Dropped total .. clients
DEBUG Dropped clients with id: 425324364,178617697,238476823...

User interface and logging

Property Description Default
wrench.logging.verbose (Since 2014.11.05) If set to false, the amount of logging is reduced. Suggested setting for stabilized production systems. true
wrench.ui.enabled (Since 2016.01.01) Set to true to enable the web user interface of Wrench that allows on-the-fly configuration of Wrench as well as management functions. false
wrench.ui.port (Since 2016.01.01) The TCP port used by the web user interface. 4567

This is how the web user interface looks like:

wrench user interface 2 wrench user interface 3

The user interface becomes available when the Wowza application in which Wrench is set up is actually started. This happens when a stream is published into that application or when the first player connects. This is what you should see in the logs if the UI is configured properly:

15:22:01 WMSLogger wrenchexample1 INFO - Started Wrench UI on http://localhost:4567/wrench/login
15:22:01 WMSLogger wrenchexample1 INFO - wrenchexample1/_definst_
15:22:01 WMSLogger wrenchexample1 INFO -
15:22:01 SparkServer wrenchexample1 INFO - == Spark has ignited ... 
15:22:01 SparkServer wrenchexample1 INFO - >> Listening on 0.0.0.0:4567
15:22:01 Server wrenchexample1 INFO - jetty-9.0.z-SNAPSHOT
15:22:01 AbstractConnector wrenchexample1 INFO - Started ServerConnector@31a44027{HTTP/1.1}{0.0.0.0:4567}

The username and password for login are those of the Wowza Streaming Engine Manager that can be found in the admin.password file under Wowza config directory.

REST API

Wrench comes with a fully functional REST API that exposes certain management features for easier integration with external systems. To enable the REST API, you need to set wrench.ui.enabled to true and set wrench.rest.api.authentication to false in order to allow external access to the API without valid session cookie that you can obtain by logging in via the UI.

You can set the port on which Wrench listens to requests with the wrench.ui.port paramter. If not set, by default it is 4567.

The REST API has preconfigured CORS filter so that it will respond to CORS preflight requests (OPTIONS) and will allow access from any server. Please note that the endpoints don't have authentication yet so you need to make sure that they are only accessible from your intranet and not public. This will be addressed in upcoming releases.

GET /wrench/manage/kick/{usernameOrSessionId} - immediately terminate all sessions associated to the specified username or session id. Please note that username comparison is case insensitive.

Response: { "username" "john": , "kickCount": 2 }

GET /wrench/manage/sessions - return a list of all current sessions with details, eg.

[
 {sessionid: 123, username: "john", ip: "192.168.1.1", streamname: "football_720p", connecttime: 100000, elapsedtime: 60, token: "asdf123", encoder: false, bitratelimit: 100000, byteratein: 0, byterateout: 100, totalinbytes: 100, totaloutbytes: 100000}
]

Fine tune logging

When using Wrench in multiple applications on the same server, you might want to inject the Wowza application name into the log messages, so you can separate the interleaved events. (You can also achieve this by configuring different logfile for each application). Wrench puts the applicationName and applicationInstanceName into the so called MDC context of log4j. This allows you to specify these in the log output pattern this way:

# Console appender
log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%d{HH:mm:ss} %C{1} %X{applicationName} %-5p - %m%n

This will result in the following output on stdout:

15:22:01 WMSLogger wrenchexample1 INFO - Client connecting with id 307819994 and query string
 ...
15:22:01 WMSLogger wrenchexample1 INFO - Accepted encoder connection from IP 127.0.0.1
15:23:02 WMSLogger wrenchexample1 INFO - Performing monitor activity over 1 connected clients (rtmp: 1, http: 0, rtp: 0)
15:23:02 WMSLogger wrenchexample1 INFO - Wrench Monitor finished successfully in 2ms