# Wowza Streaming Engine

## Wowza Load Balancer AddOn 4.0

Wowza Load Balancer AddOn is a module that enables you to redirect client connections across multiple Wowza Streaming Engine installations when a single Wowza Streaming Engine installation can't service all of the connections.

Load Balancer AddOn supports the following streaming protocols for live and video on demand (VOD) applications:

- Adobe HTTP Dynamic Streaming (HDS)
- Apple HTTP Live Streaming (HLS)
- Microsoft Smooth Streaming
- Real Time Messaging Protocol (RTMP)
- Real Time Streaming Protocol (RTSP)

> Note: Wowza Load Balancer AddOn 4.0 is only compatible with Wowza Streaming Engine™ software.

## Installation

A load-balancing configuration requires you to set up a Wowza server (the "Load Balancer") that directs client connections to additional Wowza servers (the "Servers") that handle the connections. The Servers periodically send load and status information to the Load Balancer so that it can track Server load and availability. This section shows you how to set up the Load Balancer and Server installations.

### Configuring the Load Balancer

Use the instructions in this section to configure the Wowza Streaming Engine server that you want to use as the Load Balancer.

1. Install the Load Balancing AddOn package files:
   1. Unzip the package file into a temporary folder.
   2. Copy the [package]/lib/wms-plugin-loadbalancer.jar file to the [install-dir]/lib/ folder in the Wowza Streaming Engine installation.

   For detailed installation instructions, see the Wowza Dynamic Load Balancing AddOn User's Guide (WowzaDynamicLoadBalancingAddOn_UsersGuide.pdf) in the downloaded package file.

2. Open the [install-dir]/conf/Server.xml file in a text editor and add the following server listener to the <ServerListeners> section in the file:

       <ServerListener>
       	<BaseClass>com.wowza.wms.plugin.loadbalancer.general.LoadBalancerServer</BaseClass>
       </ServerListener>

   See the Wowza Dynamic Load Balancing AddOn User's Guide (WowzaDynamicLoadBalancingAddOn_UsersGuide.pdf) for an example that shows the Server.xml configuration for the Load Balancer.

3. Open the [install-dir]/conf/Server.xml file in a text editor and add the following properties to the <Properties> section at the bottom of the file:

       <!-- Properties defined here will be added to the IServer.getProperties() collection -->
       <Properties>
       	<Property>
       		<Name>loadbalanceType</Name>
       		<Value>Server,Client</Value>
       		<Type>String</Type>
       	</Property>
       	<Property>
       		<Name>loadbalanceKey</Name>
       		<Value>123456789012345</Value>
       		<Type>String</Type>
       	</Property>
       	<Property>
       		<Name>loadbalanceServerIP</Name>
       		<Value>[Load Balancer IP address (xxx.xxx.x.xxx)]</Value>
       		<Type>String</Type>
       	</Property>
       	<Property>
       		<Name>loadbalanceServerPort</Name>
       		<Value>1935</Value>
       		<Type>String</Type>
       	</Property>
       	<Property>
       		<Name>loadbalanceDecisionOrder</Name>
       		<Value>Bandwidth,Connection</Value>
       		<Type>String</Type>
       	</Property>
       	<Property>
       		<Name>loadbalanceIgnoreClients</Name>
       		<Value>FMLE</Value>
       		<Type>String</Type>
       	</Property>
       	<Property>
       		<Name>loadbalanceBandwidthEnable</Name>
       		<Value>On</Value>
       		<Type>String</Type>
       	</Property>
       	<Property>
       		<Name>loadbalanceBandwidthLimit</Name>
       		<Value>50000</Value>
       		<Type>String</Type>
       	</Property>
       	<Property>
       		<Name>loadbalanceConnectionEnable</Name>
       		<Value>On</Value>
       		<Type>String</Type>
       	</Property>
       	<Property>
       		<Name>loadbalanceConnectionLimit</Name>
       		<Value>100</Value>
       		<Type>String</Type>
       	</Property>
       </Properties>

   See the Wowza Dynamic Load Balancing AddOn User's Guide (WowzaDynamicLoadBalancingAddOn_UsersGuide.pdf) for details about these (and additional) properties and for an example that shows the Server.xml configuration for the Load Balancer.

4. Open the [install-dir]/conf/VHost.xml file in a text editor and add the following HTTP Providers to the <HTTPProviders> section for the Default Streaming host port (Be sure that they're the first entries in the <HTTPProviders> section.):

       <HTTPProvider>
       	<BaseClass>com.wowza.wms.plugin.loadbalancer.http.LoadBalancerPublicInterface</BaseClass>
       	<RequestFilters>redirect*</RequestFilters>
       	<AuthenticationMethod>none</AuthenticationMethod>
       </HTTPProvider>
       <HTTPProvider>
       	<BaseClass>com.wowza.wms.plugin.loadbalancer.http.LoadBalancerInterface</BaseClass>
       	<RequestFilters>*loadbalancerInterface</RequestFilters>
       	<AuthenticationMethod>none</AuthenticationMethod>
       </HTTPProvider>
       <HTTPProvider>
       	<BaseClass>com.wowza.wms.plugin.loadbalancer.http.LoadBalancerInformation</BaseClass>
       	<RequestFilters>*loadbalancerInfo</RequestFilters>
       	<AuthenticationMethod>admin-digest</AuthenticationMethod>
       </HTTPProvider>

   See the Wowza Dynamic Load Balancing AddOn User's Guide (WowzaDynamicLoadBalancingAddOn_UsersGuide.pdf) for details about these HTTP Providers and for an example that shows the VHost.xml configuration for the Load Balancer.

5. Restart the Wowza Streaming Engine. For details, see Start the software.

### Configuring the load-balancing Servers

Use the instructions in this section to configure one or more Wowza Streaming Engine load-balancing Servers that fulfill client requests that are redirected to them from the Load Balancer.

1. Install the Load Balancing AddOn package files:
   1. Unzip the package file into a temporary folder.
   2. Copy the [package]/lib/wms-plugin-loadbalancer.jar file to the [install-dir]/lib/ folder in the Wowza Streaming Engine installation.

   For detailed installation instructions, see the Wowza Dynamic Load Balancing AddOn User's Guide (WowzaDynamicLoadBalancingAddOn_UsersGuide.pdf) in the downloaded package file.

2. Open the [install-dir]/conf/Server.xml file in a text editor and add the following server listener to the <ServerListeners> section in the file:

       <ServerListener>
       	<BaseClass>com.wowza.wms.plugin.loadbalancer.general.LoadBalancerServer</BaseClass>
       </ServerListener>

   See the Wowza Dynamic Load Balancing AddOn User's Guide (WowzaDynamicLoadBalancingAddOn_UsersGuide.pdf) for an example that shows the Server.xml configuration for the Load Balancer.

3. Open the [install-dir]/conf/Server.xml file in a text editor and add the following properties to the <Properties> section at the bottom of the file:

       <!-- Properties defined here will be added to the IServer.getProperties() collection -->
       <Properties>
       	<Property>
       		<Name>loadbalanceType</Name>
       		<Value>Client</Value>
       		<Type>String</Type>
       	</Property>
       	<Property>
       		<Name>loadbalanceKey</Name>
       		<Value>123456789012345</Value>
       		<Type>String</Type>
       	</Property>
       	<Property>
       		<Name>loadbalanceServerIP</Name>
       		<Value>[Load Balancer (not this Server) IP address (xxx.xxx.x.xxx)]</Value>
       		<Type>String</Type>
       	</Property>
       	<Property>
       		<Name>loadbalanceServerPort</Name>
       		<Value>1935</Value>
       		<Type>String</Type>
       	</Property>
       	<Property>
       		<Name>loadbalanceBandwidthEnable</Name>
       		<Value>On</Value>
       		<Type>String</Type>
       	</Property>
       	<Property>
       		<Name>loadbalanceBandwidthLimit</Name>
       		<Value>50000</Value>
       		<Type>String</Type>
       	</Property>
       	<Property>
       		<Name>loadbalanceConnectionEnable</Name>
       		<Value>On</Value>
       		<Type>String</Type>
       	</Property>
       	<Property>
       		<Name>loadbalanceConnectionLimit</Name>
       		<Value>100</Value>
       		<Type>String</Type>
       	</Property>
       </Properties>

   See the Wowza Dynamic Load Balancing AddOn User's Guide (WowzaDynamicLoadBalancingAddOn_UsersGuide.pdf) for details about these (and additional) properties and for an example that shows the Server.xml configuration for the Load Balancer.

4. Restart the Wowza Streaming Engine. For details, see Start the software.

## Redirection

The load-balancing redirection interfaces on the Load Balancer server enable you to provide a single URL to clients in the following basic form:

    [protocol]://[load-balancer-ip-address]:1935/redirect/[application-name]/[stream-name]?scheme=[http-transmission-scheme]

The [load-balancer-ip-address] is the IP address of the Wowza Load Balancer that you configured in Load Balancer server properties. The scheme URL query is used to specify the manifest file format in the redirect URL that's returned to clients and isn't used for RTMP or RTSP redirection.

A client is then redirected to an available load-balancing Server via a URL that has the following basic form:

    [protocol]://[load-balanced-server-ip-address]:1935/[application-name]/[stream-name]?[manifest]

Notice that the "redirect" part of the request URL is removed in the redirect URL. The [load-balanced-server-ip-address] is either the IP address of the Wowza Load Balancer that you configured in the Load Balancer property configuration or the IP address of a load-balancing Server that you configured in the Server property configuration, depending on the load on the system.

> Note: When the loadbalanceType property value is set to Server,Client on the Load Balancer, it's also a load-balancing Server that can fulfill the client request if not overloaded. Setting this property value to Server means that the Load Balancer will redirect all client requests to connected load-balancing Servers.

A Wowza load-balancing system running on Wowza Streaming Engine software supports redirection over the following protocols:

- HTTP
- RTMP
- RTSP

### HTTP redirection

The HTTP redirection interface enables you to provide a single URL that redirects clients to an available load-balancing Server.

> Note: HTTP clients are redirected using the HTTP 302 response status code. Your client must support the HTTP 302 code for load balancing to work. RTMP clients that use HTTP requests must support the returned XML (see below).

#### Apple HLS (M3U8)

An example URL used to redirect Apple HLS clients is:

    http://[load-balancer-ip-address]:1935/redirect/[application-name]/[stream-name]?scheme=m3u8

In this example, Apple HLS clients are redirected to:

    http://[load-balanced-server-ip-address]:1935/[application-name]/[stream-name]/playlist.m3u8

#### Adobe HDS (F4M)

An example URL used to redirect Adobe HDS clients is:

    http://[load-balancer-ip-address]:1935/redirect/[application-name]/[stream-name]?scheme=F4M

In this example, Adobe HDS clients are redirected to:

    http://[load-balanced-server-ip-address]:1935/[application-name]/[stream-name]/manifest.f4m

#### Microsoft Smooth Streaming (Manifest)

An example URL used to redirect Smooth Streaming clients is:

    http://[load-balancer-ip-address]:1935/redirect/[application-name]/[stream-name]?scheme=Manifest

In this example, Smooth Streaming clients are redirected to:

    http://[load-balanced-server-ip-address]:1935/[application-name]/[stream-name]/Manifest

#### RTMP XML (RTMP)

> Note: Not all RTMP clients support XML redirection over HTTP.

An example URL used to redirect RTMP clients is:

    http://[load-balancer-ip-address]:1935/redirect/[application-name]/[stream-name]/loadbalancer.smil

In this example, an RTMP client using HTTP requests gets XML returned similar to:

    <xml version="1.0"?>
    <smil>
       <head>
          <meta base="[load-balanced-server-ip-address]:1935/[application-name]/" />"
       </head>
       <body>
          <video src="[stream-name]" />
       </body>
    </smil>

### RTMP redirection

To add RTMP redirection functionality to the Load Balancer, configure the load-balancing system, add an application named 'redirect', and then add the following module to the application's Application.xml file. Be sure to add it "after" the last <Module> that's included in the <Modules> section in Application.xml. The following example shows the redirection module named redirect:

    <Module>
    	<Name>Redirect</Name>
    	<Description>Redirect</Description>
    	<Class>com.wowza.wms.plugin.loadbalancer.redirect.ClientConnections</Class>
    </Module>

This module returns an RTMP redirect to clients that connect to the Load Balancer, except for those that are configured to be ignored in the loadbalanceIgnoreClients property in the Server.xml file. Wowza edge servers that connect to a Load Balancer that's also an origin server in a live stream repeater (origin/edge) configuration are also ignored.

An example URL used to redirect RTMP clients is:

    rtmp://[load-balancer-ip-address]:1935/redirect/[application-name]/[stream-name]

In this example, RTMP clients are redirected to:

    rtmp://[load-balanced-server-ip-address]:1935/[application-name]/[stream-name]

> Notes:
> - You don't need to add this module if you've already configured RTSP redirection.
> - Not all RTMP clients support redirection via the RTMP protocol.

### RTSP redirection

To add RTSP redirection functionality to the Load Balancer, configure the load-balancing system, add an application named 'redirect', and then add the following module to application's Application.xml file. Be sure to add it "after" the last <Module> that's included in the <Modules> section in Application.xml. The following example shows the redirection module named redirect:

    <Module>
    	<Name>Redirect</Name>
    	<Description>Redirect</Description>
    	<Class>com.wowza.wms.plugin.loadbalancer.redirect.ClientConnections</Class>
    </Module>

An example URL used to redirect RTSP clients is:

    rtsp://[load-balancer-ip-address]:1935/redirect/[application-name]/[stream-name]

In this example, RTSP clients are redirected to:

    rtsp://[load-balanced-server-ip-address]:1935/[application-name]/[stream-name]

> Notes:
> - You don't need to add this module if you've already configured RTMP redirection.
> - Not all RTSP clients support redirection via the RTSP protocol.

© 2014-2015 Wowza Media Systems, LLC. All rights reserved.