Set Up Red5 Pro Clustering with Origins and Edges

Configure Red5 Pro clustering to scale live streams across origin and edge nodes, with cluster.xml reference, topology examples, and enable/disable steps.

Red5 Pro clustering connects multiple server nodes so that live streams published to one node are automatically distributed to others. This lets you serve more concurrent viewers than a single server can handle and gives you the ability to spread viewers across geographic regions. You configure the relationships between nodes through a shared cluster.xml file, and the cluster plugin handles stream replication between origins and edges at runtime.

Clustering requires a production Red5 Pro license. Trial and Developer license types do not support the clustering plugin.

Terminology

Understanding the role each node plays is essential before you configure anything.

Cluster

One or more active Red5 Pro server instances working together to make real-time data streams available for consumption. Streams are usually audio and video, but the cluster can carry any real-time data.

Server node

A single Red5 Pro server instance participating in an active cluster.

Origin

An origin node accepts publishers. It is the ingest point for live streams. Origins can also serve subscribers directly. A standalone Red5 Pro server acts as both an origin and an edge simultaneously.

Edge

An edge node accepts subscribers. It connects to one or more origins, pulls stream data from them, and delivers that data to viewers. An edge can be configured to connect to multiple origins for redundancy.

Relay

An intermediary node that sits between an origin and an edge — used in daisy-chain topologies where geographic distance makes a direct origin-to-edge connection impractical.

Transcoder

A node that performs codec conversion or adaptive bitrate transcoding. Used in Stream Manager autoscaling deployments to convert streams into multiple quality levels.

Broadcaster

The publishing client — typically a device with a webcam and microphone, a mobile phone, or a software encoder such as OBS. Publishers connect directly to an origin node.

When to use clustering

Multiple concurrent viewers

When a single server cannot sustain the viewer load, add edge nodes. Each edge independently serves subscribers so the origin is not overwhelmed.

Geographic distribution

Place edge nodes closer to your audience. Viewers connect to the nearest edge instead of reaching all the way to the origin.

Publisher redundancy

Add multiple origins so publishers have more than one ingest point. Edges that reference multiple origins reconnect automatically if one origin fails.

Autoscaling

For dynamic workloads, pair clustering with Stream Manager 2.0. Stream Manager provisions and removes nodes automatically in response to load, rather than requiring you to manage a fixed pool.

For dynamic production workloads where viewer counts fluctuate, Stream Manager 2.0 with autoscaling is the recommended approach. Static clustering is best suited for fixed, predictable deployments.

Configuration reference

All cluster configuration lives in conf/cluster.xml on each Red5 Pro server. The file is a Spring Bean definition. You must restart Red5 Pro after editing it.

Property	Description	Default
origins	List of origin IP addresses (and optional ports) that an edge connects to. Leave empty on a pure origin node.	empty
password	Shared secret used by edges to authenticate with origins. Must be identical across all nodes in a cluster. Lowercase only — no capital letters.	changeme
publicIp	The public IP address of the current server. Used by the round-robin servlet to return the correct address to subscribers.	0.0.0.0
publicPort	The RTMP port that this server is reachable on.	1935
privateInstance	When true, this node is excluded from the round-robin subscriber routing. Set to true on origins you want to reserve for publishing only.	false
retryDuration	Seconds an edge waits before retrying a lost connection to an origin.	30

The password value cannot contain capital letters. Using uppercase characters causes authentication failures between edge and origin nodes.

Configuring an origin node

On an origin node, the origins list is left empty because the origin does not connect outward to another server. The key properties to set are password, publicIp, and optionally privateInstance.

1. Open cluster.xml

   Edit conf/cluster.xml in your Red5 Pro installation directory.

2. Set the cluster password

   Replace changeme with your chosen password. Use only lowercase letters, numbers, and symbols.

3. Set the public IP

   Replace 0.0.0.0 in the publicIp property with the public IP address of this origin server.

4. Configure round-robin participation

   Leave privateInstance as false if you want the origin to serve subscribers directly alongside the edges. Set it to true if you want subscribers to be routed only to edge nodes.

5. Restart Red5 Pro

   Any change to cluster.xml requires a server restart to take effect.

conf/cluster.xml (origin)

<bean name="clusterConfig" class="com.red5pro.cluster.ClusterConfiguration">
  <property name="origins">
    <list>
      <!-- Origins do not list themselves here; leave empty -->
    </list>
  </property>

  <!-- Shared cluster password — lowercase only -->
  <property name="password" value="your-cluster-password" />

  <!-- This server's public IP -->
  <property name="publicIp" value="203.0.113.10" />

  <!-- RTMP port (default 1935) -->
  <property name="publicPort" value="1935" />

  <!-- Set to true to exclude this node from subscriber round-robin -->
  <property name="privateInstance" value="false" />

  <!-- Retry interval in seconds (used by edges, has no effect on origin) -->
  <property name="retryDuration" value="30" />
</bean>

Configuring an edge node

An edge node must reference at least one origin. It uses the same password value and connects outward to each IP in the origins list.

1. Open cluster.xml

   Edit conf/cluster.xml on the edge server.

2. Add origin IPs

   Uncomment and populate <value> entries in the origins list with the public IP (and optional port) of each origin. Add one <value> entry per origin.

3. Set the same cluster password

   Use the identical password you set on the origin. The edge uses this to authenticate when it connects.

4. Set the edge's public IP

   Replace 0.0.0.0 in the publicIp property with the public IP of this edge server.

5. Configure round-robin participation

   Leave privateInstance as false so that subscribers are routed to this edge. Set it to true to hide this edge from the round-robin servlet.

6. Restart Red5 Pro

   Restart Red5 Pro on the edge. You can add new edge nodes to a running cluster without restarting the origin.

conf/cluster.xml (edge)

<bean name="clusterConfig" class="com.red5pro.cluster.ClusterConfiguration">
  <property name="origins">
    <list>
      <!-- Add each origin's IP; include port only if not using default 1935 -->
      <value>203.0.113.10</value>
      <!-- <value>203.0.113.11:1935</value> -->
    </list>
  </property>

  <!-- Must match the origin's cluster password exactly — lowercase only -->
  <property name="password" value="your-cluster-password" />

  <!-- This edge server's public IP -->
  <property name="publicIp" value="203.0.113.55" />

  <!-- RTMP port (default 1935) -->
  <property name="publicPort" value="1935" />

  <!-- Set to true to exclude this edge from subscriber round-robin -->
  <property name="privateInstance" value="false" />

  <!-- Seconds to wait before retrying connection to an unavailable origin -->
  <property name="retryDuration" value="30" />
</bean>

Common cluster topologies

One origin, one edge

The simplest multi-server configuration. Both nodes participate in round-robin, so subscribers may be routed to either.

Set privateInstance to false on both the origin and the edge. The edge connects to the origin IP.

Publishers connect directly to the origin IP. Subscribers call the round-robin servlet at http://<origin-ip>:5080/cluster and are directed to either the origin or the edge.

One origin, three edges

The origin is reserved for publishing only. Subscribers receive only edge addresses.

Set privateInstance to true on the origin and false on all three edges. Each edge lists the origin IP in its origins property.

Publishers connect to the origin IP. Subscribers call the round-robin servlet and receive one of the three edge addresses.

Multiple origins

Adds publisher redundancy. Each edge lists all origin IPs in its origins list.

Restart the edges and the new origin when adding the second origin. Publishers can use either origin IP. All streams are replicated to all edges regardless of which origin ingested them.

Daisy chain

Used when publishers are in one region and subscribers are in a geographically distant region.

An intermediary server acts as an edge to the true origin and as an origin to the final edge. Each server’s origins property points to the previous node in the chain. Configure retryDuration to a low value so reconnection after a chain break is fast.

Round-robin subscriber routing

The round-robin servlet is included in every Red5 Pro installation and requires no configuration changes. Subscribers query it to receive the address of the node they should connect to:

GET http://<origin-ip>:5080/cluster

The servlet returns an IP address drawn from the pool of nodes where privateInstance is false. Your subscriber client then connects to the returned address.

Enabling and disabling clustering

Clustering is enabled by default when the cluster plugin JARs are present.

To disable clustering

1. Set nodeType to off

   Edit conf/cluster.xml and change the nodeType property from auto to off:

   <property name="nodeType" value="off" />
   
2. Comment out Spring beans

   In webapps/red5-default.xml, comment out the following two bean definitions:

   <!-- <bean id="clusterServiceResolver"
          class="com.red5pro.cluster.plugin.ClusterServiceResolver"/> -->
   
   <!-- <bean id="applicationEventListener"
          class="com.red5pro.cluster.plugin.event.ApplicationEventListener" /> -->
   
3. Remove the plugin JARs

   Delete the following files from the plugins/ directory:

   • red5pro-cluster-plugin-*.jar
   • red5pro-autoscale-plugin-*.jar
4. Restart Red5 Pro

   Restart the server. It will run as a standalone node without any cluster participation.

Extending clustering with the application adapter

The cluster API lets you broadcast application-level events — such as room joins — across all nodes in the cluster. The ApplicationAdapter can query whether it is currently running on an edge or an origin, then use the cluster service to dispatch messages to:

• all clustered instances
• all edge nodes only
• all origin nodes only
• a specific instance
• all instances except one or more

This is the same API used by the Red5 Pro Second Screen SDK. Integrate it when your application needs to synchronize session state across nodes that do not automatically share ApplicationAdapter events.