> ## Documentation Index
> Fetch the complete documentation index at: https://red5.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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

## Terminology

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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Server node">
    A single Red5 Pro server instance participating in an active cluster.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Transcoder">
    A node that performs codec conversion or adaptive bitrate transcoding. Used in Stream Manager autoscaling deployments to convert streams into multiple quality levels.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## When to use clustering

<CardGroup cols={2}>
  <Card title="Multiple concurrent viewers" icon="users">
    When a single server cannot sustain the viewer load, add edge nodes. Each edge independently serves subscribers so the origin is not overwhelmed.
  </Card>

  <Card title="Geographic distribution" icon="globe">
    Place edge nodes closer to your audience. Viewers connect to the nearest edge instead of reaching all the way to the origin.
  </Card>

  <Card title="Publisher redundancy" icon="shield-check">
    Add multiple origins so publishers have more than one ingest point. Edges that reference multiple origins reconnect automatically if one origin fails.
  </Card>

  <Card title="Autoscaling" icon="arrows-up-down">
    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.
  </Card>
</CardGroup>

<Tip>
  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.
</Tip>

## 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`       |

<Warning>
  The `password` value cannot contain capital letters. Using uppercase characters causes authentication failures between edge and origin nodes.
</Warning>

## 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`.

<Steps>
  <Step title="Open cluster.xml">
    Edit `conf/cluster.xml` in your Red5 Pro installation directory.
  </Step>

  <Step title="Set the cluster password">
    Replace `changeme` with your chosen password. Use only lowercase letters, numbers, and symbols.
  </Step>

  <Step title="Set the public IP">
    Replace `0.0.0.0` in the `publicIp` property with the public IP address of this origin server.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Restart Red5 Pro">
    Any change to `cluster.xml` requires a server restart to take effect.
  </Step>
</Steps>

```xml conf/cluster.xml (origin) theme={null}
<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.

<Steps>
  <Step title="Open cluster.xml">
    Edit `conf/cluster.xml` on the edge server.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Set the same cluster password">
    Use the identical password you set on the origin. The edge uses this to authenticate when it connects.
  </Step>

  <Step title="Set the edge's public IP">
    Replace `0.0.0.0` in the `publicIp` property with the public IP of this edge server.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Restart Red5 Pro">
    Restart Red5 Pro on the edge. You can add new edge nodes to a running cluster without restarting the origin.
  </Step>
</Steps>

```xml conf/cluster.xml (edge) theme={null}
<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

<Tabs>
  <Tab title="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.
  </Tab>

  <Tab title="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.
  </Tab>

  <Tab title="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.
  </Tab>

  <Tab title="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.
  </Tab>
</Tabs>

## 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

<Steps>
  <Step title="Set nodeType to off">
    Edit `conf/cluster.xml` and change the `nodeType` property from `auto` to `off`:

    ```xml theme={null}
    <property name="nodeType" value="off" />
    ```
  </Step>

  <Step title="Comment out Spring beans">
    In `webapps/red5-default.xml`, comment out the following two bean definitions:

    ```xml theme={null}
    <!-- <bean id="clusterServiceResolver"
           class="com.red5pro.cluster.plugin.ClusterServiceResolver"/> -->

    <!-- <bean id="applicationEventListener"
           class="com.red5pro.cluster.plugin.event.ApplicationEventListener" /> -->
    ```
  </Step>

  <Step title="Remove the plugin JARs">
    Delete the following files from the `plugins/` directory:

    * `red5pro-cluster-plugin-*.jar`
    * `red5pro-autoscale-plugin-*.jar`
  </Step>

  <Step title="Restart Red5 Pro">
    Restart the server. It will run as a standalone node without any cluster participation.
  </Step>
</Steps>

## 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.