Step-by-Step Wrench Setup Guide

This article covers the steps you need to make in order to install Wrench on your Wowza Streaming Engine®. Although this is not as simple as running an installer and pressing Next, Next, Finish on a wizard screen, it is not rocket science. By using Wrench module in your streaming system you are able to add authentication (which is sometimes vaguely referred to as password protection) to your live or on-demand (VOD) streams, regardless the actual streaming technology you are using. RTMP, HLS and MPEG-DASH are all supported. This authentication can be both applied to players or encoders or both in the system. After determining the identity (username) of your encoder or player Wrench can perform further authorization along these line:

  • Can this user watch this or that stream? Did he buy "ticket"?
  • Can this user publish this or that stream?
  • For how long can the user watch / publish the stream?

The administrator interface of Wrench allows you to monitor the list of people currently watching your stream and optionally kick off any user by username who deserves it.

Prerequisites

  • Have Wowza Streaming Engine installed on your server up and runnig
  • Have access to the Engine Manager with access to advanced settings (see the attached screenshot)

Download Wrench jar file

Wrench ships as a single .jar file named as wrench-yyyy.mm.dd.jar that you can download from here and then you need to copy it into the lib directory of your Wowza installation. On Windows systems this is typically at C:\Program Files\WowzaStreamingEngine\lib and on Linux installations this is at /usr/local/WowzaStreamingEngine/lib.

If you plan to connect to any database in your setup (this is quite typical, but recent versions allow you to work with external webservices instead of database) you need to download it's JDBC connector jar file and put that also into the lib directory. In the FAQ section you can find a table with the download links for most typical databases.

You need to restart the whole Streaming Engine using the restart button on the right hand side that is visible when you choose "Server Setup" so that the new jar files are loaded.

Create your streaming application

You need to create your own streaming application using the Manager interface. There are archetypes for live streaming and video-on-demand (vod), as well as for edge and origin. These differ in some key configurations, so make sure you pick the right one based on the help documentation of Wowza. In this example I am going with a new Live (single server or origin) application which I'll call "wrenchexample2".

Click on the "+ Application" button on the left menu

Give a name to your application

Switch on Wrench module

Select your brand new application and navigate to the Modules tab. (If you don't see this tab then you don't have the "access to advanced settings", so scroll back up a bit to see what is that)

Click on the Edit button and then on the "+ Add Module..." button and fill in the form with the below data

Restart the application as suggested by the popup message.

Start your application

It might sound a bit weird, but when you restart the application, technically the modules are not started until the first client connects (player or encoder). So at this point Wrench is configured and is sleeping. One of the simplest way to trigger the application start is invoking a URL like this from your browser:

http://localhost:1935/wrenchexample2/boot/playlist.m3u8

You might need to edit the hostname and the port to match your system and it only works if you have HTTP streaming enabled. Otherwise you can push your stream from your encoder or use the test players to trigger the application.

Once triggered, you should see something like this in your wowzastreamingengine_access.log file. (You can inspect the log file using the Engine Manager)

20:42:24 WMSLogger wrenchexample2 INFO - Starting application wrenchexample2/_definst_
20:42:24 WMSLogger wrenchexample2 INFO - Starting Wrench 2016.04.13, licensed to Free version
20:42:24 WMSLogger wrenchexample2 INFO - License number: 1
20:42:24 WMSLogger wrenchexample2 INFO - Verbose logging mode is on
20:42:24 WMSLogger wrenchexample2 INFO - No JDBC driver is specified, going to no-database mode. SQL dependent features will not work.
20:42:24 WMSLogger wrenchexample2 INFO - Expected token parameter is: t
20:42:24 WMSLogger wrenchexample2 INFO - No token resolver query or url is specified, all tokens will resolve to user 'anonymous'
20:42:24 WMSLogger wrenchexample2 INFO - RTP protocol checking is enabled
20:42:24 WMSLogger wrenchexample2 INFO - HTTP Streamer Request checking is disabled
20:42:24 WMSLogger wrenchexample2 INFO - Secure transport forcing is disabled
20:42:24 WMSLogger wrenchexample2 INFO - Publish encoder flag checking is disabled
20:42:24 WMSLogger wrenchexample2 INFO - IP checking is disabled
20:42:24 WMSLogger wrenchexample2 INFO - Concurrent player checking is disabled
20:42:24 WMSLogger wrenchexample2 INFO - Token expiration checking is disabled
20:42:24 WMSLogger wrenchexample2 INFO - Switchable public mode is disabled
20:42:24 WMSLogger wrenchexample2 INFO - Wrench Monitor thread started with period time: 60
20:42:24 WMSLogger wrenchexample2 INFO - Wrench web UI is not enabled

This is how you can inspect the access log on the web interface

This is what you should see if Wrench was set up correctly

Enable Wrench UI

Starting from version 2016.01.01 Wrench comes with a handy UI where you are able to edit it's configuration on the fly. The configuration is technically persisted in the Application.xml file but this saves you from manually editing the xml file, which is error prone.

The UI is not enabled by default, that is what you can see in the logs too Wrench web UI is not enabled. To switch it on, you need to add a custom configuration property to your application.

Navigate to the Properties tab of your wrenchexample2 application.

Click on the "Custom" button in the Quick links section and then click on the Edit button to add a custom property to your application, and then "Add Custom Property..". Fill in the form as you see below:

By default the UI will be available on port 4567. You can change this by adding an optional integer parameter called wrench.ui.port˙.

This is how it should look like with both properties added

Now restart your application again and trigger it and then check the logs again, you should now see this:

Started Wrench UI on http://localhost:4567/wrench/login

Copy-past this link into your browser to get to the Wrench login page:

You can log in with the same username and password that you use to log into the Engine Manager. After loggin in you should see this dashboard:

There is a sea of configuration paramters to tweak here, please refer to other tutorials for instructions on setting up typical security scenarios for password protecting your HLS or MPEG-DASH streams, or to implement pay-per-view or pay-per-minute.

In case of any questions or problems feel free to reach out to help@streamtoolbox.com