XUI.one Load Balancer Setup: Scale an IPTV Panel

A single server runs out of road in one of three places: CPU (transcoding), egress bandwidth, or your tolerance for a single point of failure. An XUI.one load balancer is how you move past that limit without rebuilding the panel: you keep one main server for the panel and database, and add delivery nodes that carry the streaming traffic. This guide continues How to install Xtream UI (XUI.one) on Ubuntu 22.04. We assume the main server is already installed, firewalled and reachable, and we do not repeat that setup here.

One caveat up front: XUI.one is a commercial panel, and its menu labels, installer behavior and supported OS list change between releases. Where the exact wording depends on your version, we describe the step by meaning. Check your panel's own documentation or your vendor before you run anything on production.

When you need an XUI.one load balancer

Add nodes when one of these is true:

• Egress is the bottleneck. Peak viewers multiplied by bitrate is close to the port speed of the main server.
• CPU is the bottleneck. Transcoding or many simultaneous restreams keep the cores near 100% and the panel UI gets slow.
• You want to survive a node loss. With several delivery nodes, losing one removes capacity but not the whole service. The main server is still a single point of failure unless you design for it separately.
• You want viewers closer to the edge. Nodes in Kyiv, Amsterdam, Warsaw or Miami can serve audiences in their own region.

If none of these applies, a bigger single server is simpler to run. Scale out when you have to, not before.

Main server vs load balancer: who does what

Think of it as a control plane and a delivery plane.

Main server (control plane)

• The admin panel and reseller interface
• The MariaDB database with lines, bouquets, streams and settings
• Authentication of lines
• Your stream and VOD definitions

Load balancer node (delivery plane)

• Serving live and VOD streams to viewers
• Running the FFmpeg processes for the streams assigned to it
• Using its own CPU and its own network port for that traffic

The practical consequence: viewer bandwidth is spread across nodes, but the main server and its database remain the single source of truth. Keep the main server healthy, backed up, and not saturated by viewers. Many operators stop serving viewers from the main server entirely once the first nodes are online, and we suggest you consider that.

How streams are spread depends on your configuration. In general, a stream is assigned to one or more servers in the panel, and the panel directs a viewer's request to a node that carries the stream, taking server load into account. Exact balancing rules and any per-server limits are set in the panel and differ by version, so test with a small group of lines before moving real subscribers.

Prepare the servers

Before you touch the panel, get these in place:

1. A clean OS on every node. Use the Ubuntu release your XUI.one version lists as supported for load balancers. Do not install anything else on the node, and do not run a second web server or database on it.
2. Root access over SSH. The panel installs the node remotely, so it needs an IP address, an SSH port and root credentials (or whatever your version accepts) for the new server.
3. Hardware at least as capable as the delivery job needs. Do not under-size the nodes relative to the traffic you plan to send them.
4. A network path between main and nodes. Use a private network or VLAN if the servers are in the same facility. Across sites, use public IPs with a strict firewall. Keep latency between nodes and main server low, because the nodes depend on the main server for authentication and data.
5. Time in sync. Run the same timezone (UTC, as in the install guide) and working NTP on all servers. Mismatched clocks cause confusing token and EPG issues.

Check the hostname and connectivity from the main server:

# from the main server
ping -c 4 LB_IP
nc -vz LB_IP 22

If you changed the SSH port as recommended in the install guide, test that port instead of 22.

Firewall: the rules that matter

Do not copy a port list from a forum post. Ports differ by version and by what you configured at install time. Use these principles and fill in the actual numbers from your own panel:

• On the main server, the database must not be reachable from the internet. Allow the database port only from the IP addresses of your load balancers. Keep the admin port restricted to your own static IPs, as in step 7 of the install guide.
• On each node, open SSH only from the main server and your admin IPs, and open the streaming and client ports that your panel shows for that server to the public.
• During the remote install, some guides tell you to disable the firewall on the new node temporarily so the panel can finish. If you do, re-enable it as soon as the node shows as online and apply the rules above.

An example of locking the database to a node with UFW. Replace the port with the one your installation actually uses:

# on the main server
sudo ufw allow from LB_PUBLIC_IP to any port DB_PORT proto tcp
sudo ufw status numbered

Repeat for each node. Review the list whenever you add or retire a server.

Add the load balancer from the admin panel

The overall flow is consistent across the public guides we reviewed, even where labels differ:

1. Log in to the admin panel of the main server.
2. Open the Servers section and choose the option to install a new load balancer (in some versions this appears as "Install Load Balancer", in others under a streaming-servers list with an "Add Server" button).
3. Fill in the form:

- a name for the node, for example lb-ams-01 - the node's IP address - the SSH port (22 unless you changed it) - the SSH user (root) and its password

1. Start the installation and watch the progress screen. The panel connects over SSH, installs the components and registers the node. Reports we found put the installation at a few minutes, but that depends on the network and the server.
2. When it finishes, reboot the node if your version asks you to.

Give the process time and do not interrupt it. If it fails, read the error shown by the panel first. Common causes are the wrong SSH port, a firewall blocking the panel, a root login that is disabled on the node, or an unsupported OS.

Check that the node is healthy

Do not move subscribers until you have confirmed all of the following.

In the panel. Open the server list in the Servers section. The new node should show as online, with a recent ping and visible resource usage (CPU, memory, bandwidth). If it shows offline, the main server cannot reach it, which is almost always a firewall or SSH problem.

On the node. Check that the processes run and that the node is listening where you expect:

# on the load balancer
ss -tlnp | head -30
uptime
df -h

With a test stream. Assign one stream to the new node, then request it with a test line and look at the response headers:

curl -I "http://LB_IP:CLIENT_PORT/live/TEST_USER/TEST_PASS/STREAM_ID.ts"

A 200 response with a video content type means the node serves the stream. Use your panel's actual client port and URL format.

FFmpeg. If your streams are transcoded or restreamed, the FFmpeg processes run on the node that carries the stream:

# on the load balancer
ps aux | grep [f]fmpeg | head

If you expect FFmpeg processes and see none, the stream is probably not assigned to this node or the source is down. For GPU-based transcoding, see FFmpeg with NVENC.

Size the bandwidth first

Traffic is the usual reason you scale, so do the arithmetic before ordering anything. The formula is simple:

peak egress (Gbit/s) = concurrent viewers x average bitrate (Mbit/s) / 1000

An illustrative example, not a promise about any server: 2,000 concurrent viewers at an average of 5 Mbit/s for a 1080p channel is 10,000 Mbit/s, or 10 Gbit/s. Do not plan to run a port at 100%. If you leave 30% headroom, a 10 Gbit/s port is comfortable at around 7 Gbit/s, which is about 1,400 viewers at that bitrate. For 2,000 viewers, you would plan two to three 10G nodes, or one node with a larger port.

Your own bitrates, adaptive profiles and concurrency ratio will differ. Our guide to IPTV head-end bandwidth sizing goes through concurrency, ABR overhead and port choice in more detail.

Choosing servers for main and load balancers

The main server needs steady CPU, RAM and fast storage for the database. It does not need the biggest port, especially once viewers are served from nodes. Load balancer nodes are chosen mostly by network port and CPU. All servers below are unmetered, and prices are monthly from our catalog.

A reasonable starting layout for a first scale-out is the $139 server as the main server and one or two nodes sized to your bandwidth calculation. Choosing the main server and the nodes in the same city keeps latency low. If your audience is in several regions, place nodes in Kyiv, Amsterdam, Warsaw or Miami, with the main server on the site where you manage the panel. Stock differs by site, so tell us where you need capacity when you order.

See the full range on unmetered dedicated servers, or the 10 Gbit/s dedicated servers page if the port is your priority. We do not publish viewer-capacity benchmarks for these servers, so size from your own measurements.

Common problems

The node installs but shows offline. Check the firewall on both sides, the SSH port, and that the main server can reach the node's IP. Check that the database port is allowed from the node.

Viewers still hit the main server. The stream is probably assigned only to the main server. Add the node to the stream's server list in the panel and confirm in your test.

One node is saturated while another is idle. Review the per-server settings and the assignments of your busiest channels. Spread the heavy channels deliberately and test again.

FFmpeg processes restart in a loop. Look at the source first, then at node CPU.

Back up the main server

The main server holds your data. Back up the database on a schedule, keep a copy off-site and test the restore. Nodes can be reinstalled from the panel; the database cannot.

Content and acceptable use

XUI.one is a tool for distributing content you are licensed to distribute. Our acceptable use policy applies to every server you run, including nodes added later.

Where to go from here

With the main server and one node working, add nodes one at a time and re-check bandwidth after each. For hosting built around IPTV panels, see IPTV panel hosting and the Xtream UI / XUI.one hosting page. If you want help choosing between the tiers above, or need a layout across several sites, pick a layout on our IPTV panels page and tell us your concurrent viewers and bitrate.