The reverse proxy is a server that sits in front of your cluster and receives client connections in its place, so your main server and load balancers never show their real IPs to the outside. It does not host content: every request it takes goes to one of your real servers.

You install a reverse proxy the same way you install a load balancer (see Add a Load Balancer Server), but you click Add reverse proxy in Servers, or choose This is a reverse proxy server in the installer. Once at least one proxy is online, this page explains how you decide how the cluster uses it.

In the Servers list, a reverse proxy has the PROXY label. Instead of connections, it shows how many streams it is forwarding and its requests per second. Reverse proxies do not appear in the server selectors when you create channels, movies or series.

Requirements

  • Engine 2.3.0 or newer on the main server. Without it there is no Add reverse proxy button and no Reverse Proxy settings.
  • At least one server with the reverse proxy role installed and online.
  • For Main only and Full, a domain configured on the main server. Without one, playlists and cover images would still show a real IP.
  • For Full, every load balancer that is online must run engine 2.3.0 or newer. If one does not, the panel locks the Full option and shows the name of the server that holds it back.

After you install a proxy

  1. Point the public domain your clients use to the IP of the proxy (an A record in your DNS).
  2. If you serve HTTPS, request the certificate for that domain from Edit Server of the proxy, once the DNS already points to it.
  3. Choose the mode, as explained below.

The three modes

The settings are in Settings → Streaming (Channels & Vod) → Reverse Proxy. The Reverse proxy mode selector saves on its own the moment you change it. Changes apply on all servers within about 1 minute.

Off (default)

The reverse proxy is not used for routing. Playlists, redirects and streaming URLs contain the real IPs of your main server and your load balancers, like a setup with no proxy at all. Registered proxies are still trusted by your servers, so if some traffic keeps entering through a proxy it works normally and clients are seen with their real IP. Use this mode if you installed proxies but do not want to route traffic through them yet.

flowchart LR
    C1((Client)) --> M["Main (real IP)"]
    C2((Client)) --> L1["LB 1 (real IP)"]
    C3((Client)) --> L2["LB 2 (real IP)"]

Main only

The proxy takes over the main server's public address. Your load balancers keep serving streams with their own IPs. This is the right choice when you want to keep the main server out of direct reach and you do not mind the load balancers staying visible.

flowchart LR
    C1((Client)) --> P[Proxy]
    P --> M["Main (hidden)"]
    C2((Client)) --> L1["LB 1 (real IP)"]
    C3((Client)) --> L2["LB 2 (real IP)"]

Full

Every client connection (panel, API, playlists, live streams, VOD, widgets) enters through a proxy. The load balancers still serve the content, but the client never learns their addresses. This is the "hidden cluster" mode.

flowchart LR
    C((Client)) --> P[Proxy]
    P --> M["Main (hidden)"]
    P --> L1["LB 1 (hidden)"]
    P --> L2["LB 2 (hidden)"]

If you have several proxies, each of them can front the full cluster on its own. Proxy balancing decides how clients are spread across them.

Proxy balancing (Full mode only)

When the mode is Full, the Proxy balancing selector appears. It chooses how clients are spread across your proxies.

  • DNS (default): each client enters through the proxy its DNS lookup resolves to, and stays there. You spread the load by publishing several A records for your domain, or by adding the proxy domains to the DNS list of the main server. GeoIP rules configured on a proxy are not applied in this mode: the client goes wherever DNS sends it.
  • Load: on every redirect, the main server picks the proxy with the lowest outgoing traffic at that moment, honoring the GeoIP rules of each proxy. Load needs a domain on every proxy. A proxy without a domain is never picked by Load: it only gets the traffic that DNS sends to it directly.
flowchart LR
    subgraph DNS ["DNS balance"]
        direction LR
        A1((Client A)) --> P1[Proxy 1]
        A2((Client B)) --> P2[Proxy 2]
        A3((Client C)) --> P1
    end
    subgraph Load ["Load balance"]
        direction LR
        B1((Client)) --> LP["Proxy with lowest outgoing traffic"]
    end

Strict origins (Full mode only)

Strict origins is an on/off switch below Proxy balancing. It is the setting that actually enforces the hidden cluster.

  • With strict off, your main server and load balancers keep accepting direct connections on their streaming ports. A client that already knows a real IP (from a leaked playlist, a scraper or an old bookmark) can still reach them. Full mode hides the IPs from new clients, but strict off does not lock the door behind them.
  • With strict on, on their streaming ports your real servers only accept traffic from the proxies, from the cluster itself and from Xtream AI. Anyone else gets a timeout rather than a refusal. Other ports, such as SSH, are not affected.
flowchart TB
    subgraph OFF ["Strict OFF"]
        direction TB
        S1["Client with leaked IP"] -->|connects| M1[Main]
        PX1[Proxy] --> M1
    end
    subgraph ON ["Strict ON"]
        direction TB
        S2["Client with leaked IP"] -.->|dropped| M2[Main]
        PX2[Proxy] --> M2
    end

What strict origins changes for the rest of your setup

Two things stop working when strict is on. Both happen because your real servers refuse direct connections, not because of a bug:

  • Domain certificates move to the proxy. Let's Encrypt checks a domain on port 80 of the server that answers for it. With strict on, the main server no longer accepts that check, so the certificate for your domain must be issued on the proxy, from its Edit Server page.
  • Anything that uses a real IP on the streaming ports stops reaching your servers. External monitoring that requests a playlist or a stream from the IP of the main server, restreamers that were given a raw IP, or third-party tools that use an old hostname pointing to a real server will not get through. Point them to the proxy address and they work again. The Xtream AI panel is not affected.

Automatic fail-open

If no proxy reports for 5 minutes, the restriction lifts by itself and your real servers accept direct connections again. This way a problem on the proxies cannot take your service down. When a proxy reports again, strict origins applies again.

Working with the settings

  • The Reverse proxy mode and Proxy balancing selectors save on their own. If a change is rejected (for example, you switch to Full while an online load balancer runs an older engine), the selector goes back to its previous value and a message tells you why.
  • Under the mode you see how many proxy servers are online. If Main only or Full is locked, the reason is shown right there.
  • Proxy balancing is shown only when the mode is Full.
  • Strict origins is always visible, but you can only change it in Full mode. Until then its status reads Available in Full mode.

Common problems

Check these in order:

  1. The proxy shows as online in the Servers list. A proxy that stops reporting for more than about 2 minutes shows as Offline. Check that the engine runs on it and that it can reach your other servers.
  2. The main server runs engine 2.3.0 or newer. Without it the Reverse Proxy settings do not appear.
  3. For Full mode, every online load balancer runs 2.3.0 or newer. The panel names the server that blocks the change.
  4. For Main only and Full, the main server has a domain configured.
  5. After you enable strict origins, direct-IP tests fail on purpose. If a monitoring probe or a restreamer stops working right after you turned strict on, point it to the proxy address.
  6. The installer stops because this IP still has channels, VOD, users or watch folders. A proxy cannot host content. Move that content to another server, or delete the old server from the list, and run the installation again.

If you delete a proxy from the Servers list, your other servers stop trusting it within a minute.