Installing Wrench

1. Install the module file

Before reading on: if you prefer a video walkthrough instead of reading the documentation, please watch this YouTube video:

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

On Linux this is typically /usr/local/WowzaStreamingEngine/lib and on Windows this can be C:\Program Files\Wowza Media Systems\Wowza Streaming Engine\lib

When using Wrench together with a configuration that requires database connection, you also need to copy your database’s JDBC driver jar fileto the same lib directory, so that Wowza Streaming Engine can load it.

After copying the files, you need to restart Wowza Streaming Engine.

At ths point Wrench is ready to be configured in any of your Wowza applications.

2. Turn on the module in a Wowza application

You can use the Engine Manager interface or XML editor to enable Wrench. You can find both approaches documented below:

Select your desired Wowza application and navigate to the Modules tab. (If you don’t see this tab then you don’t have the “access to advanced settings” enabled for your user)

Application modules tab

Click on the Edit button and then on the “+ Add Module…” button and fill in the form with the below data

Application modules tab

Restart the application as suggested by the popup message.

Alternatively if you want to enable Wrench for a particular application on your server, you can also simply put the below configuration under that application’s conf/myapplication/Application.xml file:

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

3. Install License File

Without license file Wrench works in free mode with 25 concurrent user limitation. If you have purchased a license file, place it under the conf directory of your Wowza installation. The expected filename is wrench-*.license (case insensitive).

You can override/concretize the expected license file name using the wrench.license.file property in your Application.xml file. This can be either just a filename or an absolute/relative path to the license file. If multiple matching files are found, the first one is picked depending on the operating system file ordering.

If the license file is not found, you’ll see the below message in your logs:

No Wrench license file found in default location /usr/local/WowzaStreamingEngine/conf entering free mode

4. Check Installation

Restart Wowza Streaming Engine after copying the files and start streaming activity in the application where you have configured Wrench. The module only gets loaded and started up when the surrounding application is started. You can publish a live stream or connect with a player to make sure that the application is started up. The application stops after a certain amount of idle time and Wrench stops too in this case.

A simple way to wake up the application is invoking a fake playback URL from browser:

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)

INFO server comment - Wrench version: 2.0.0
INFO server comment - User limit: 25
INFO server comment - License expiration date: 2021.07.30
INFO server comment - Verbose logging mode is on
INFO server comment - Using database url 'jdbc:mysql://localhost:3306/wtbexampledb', user: 'root'
INFO server comment - Maximum pool size is set to 3, initial pool size is 2
INFO server comment - Maximum / minimum idle connection number is 3 / 1
jul. 18, 2020 11:08:50 DU. org.apache.tomcat.jdbc.pool.PooledConnection connectUsingDriver
WARNING: Not loading a JDBC driver as driverClassName property is null.
jul. 18, 2020 11:08:51 DU. org.apache.tomcat.jdbc.pool.PooledConnection connectUsingDriver
WARNING: Not loading a JDBC driver as driverClassName property is null.
INFO server comment - Database connection test passed
INFO server comment - Expected token parameter is: t
INFO server comment - Using SQL token resolver
INFO server comment - RTP/WebRTC protocol checking is enabled
INFO server comment - HTTP Streamer Request checking is disabled
INFO server comment - Secure transport forcing is disabled
INFO server comment - Publish encoder flag checking is disabled
INFO server comment - IP checking is disabled
INFO server comment - Concurrent player checking is disabled
INFO server comment - Token expiration checking is disabled
INFO server comment - HTTP request number limiting is off
INFO server comment - Switchable public mode is disabled
INFO server comment - Wrench Monitor thread started with period time: 60
INFO server comment - Performing monitor activity over 0 connected clients (rtmp: 0, http: 0, rtp: 0, webrtc: 0)
INFO server comment - Started Wrench UI on https://localhost:4567/wrench/login with SSL enabled
INFO server comment - Wrench Monitor finished successfully in 2ms

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

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

Wrench boot message

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 or you haven’t restarted the server.


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 module is disabled in your configuration.

5. Add Application Properties

Wrench’s behaviour is defined by the application properties that you can edit directly in the Application.xml file of your Wowza application or via the Engine Manager Interface. Please make sure to restart the application after altering the configuration. It is enough to restart the application, there is no need to restart the Streaming Engine itself.

You can find sample Application.xml file on GitHub:

The full reference of application properties can be found in the Application Properties