Add a load balancer server

A load balancer (LB) is a second server that runs streams and serves them to viewers. The panel installs a program called the agent on it. This document explains the installation from the panel, what the agent does, the network rules and the checks.

Before you start

• The main server is installed and healthy.
• The new server runs Debian or Ubuntu with systemd and has a public IPv4 address.
• You have the root SSH password of the new server. The panel installs the agent over SSH with a password.
• Root login with a password is allowed on the new server during the installation.
• The firewall rules in the section "Firewall rules" are possible with your provider.
• Your license is valid. With an overdue license check the panel refuses to add a server.

Which method to use

Use the panel. The panel writes the complete agent configuration, grants database access and sets up nginx on the new server.

Do not use the script install-lb.sh from the install package for a new load balancer. Answer no to the installer question Add LB now? (y/n) [n]:, which starts that script. An agent that was set up by the script alone does not have the settings it needs and stops with [Agent] AGENT_SERVER_ID is required and must be > 0.

Steps

1. Add the server in the panel

1. Log in to the panel as an administrator.
2. Open Servers and choose Add Server.
3. Enter a name and the IP address of the new server. Enter the SSH user (root), the SSH password and the SSH port (22 unless you changed it).
4. Save.

Possible message: Name and IP are required.

2. Install the agent

Start Install Server for the new entry. The panel then runs nine steps on the new server over SSH:

The panel then waits up to 60 seconds for the first heartbeat of the agent and installs the signed media runtime (ffmpeg and ffprobe) on the new server. The installation log ends with Agent heartbeat received! Installation successful.

3. Assign streams

Choose in the panel which streams run on the new server.

What the agent does

• It connects to the database of the main server and reads its own entry in the server list.
• It writes a heartbeat with load figures into the database every 30 seconds. The panel shows a server as online from this heartbeat.
• It starts and stops ffmpeg for the streams assigned to it and writes HLS segments to /app/data/hls.
• It serves /live/, /movie/, /series/ and HLS requests from viewers on its HTTP port. The main server answers a viewer request with a redirect to the load balancer when the stream runs there.
• It forwards requests that belong to the panel to the panel URL.
• It listens on a control port (6661 by default) for commands from the panel. Each command must carry the API key of the server.
• It accepts a new version of itself from the panel only when the file carries a valid signature. After a self-update it watches the service for 60 seconds and puts the previous program back when the new one does not stay up.

Firewall rules

Port 3306 on the main server:

• The database container listens on 127.0.0.1:3306 only.
• The timer xtreamgo-db-access-sync.timer runs /home/xtreamgo/scripts/db_lb_access_sync.sh every 20 seconds.
• When at least one load balancer is registered, the script starts the service xtreamgo-db-forward (a socat forwarder on the first IP address of the main server) and allows port 3306 for the load balancer IPs only. All other sources are dropped by the iptables chain XTREAMGO_DBACCESS.
• When no load balancer is registered, the forwarder is stopped and port 3306 stays closed.

You do not need to add these rules on the main server by hand. If your provider has a cloud firewall, allow port 3306 from the load balancer IP there.

The panel does not configure a firewall on the load balancer. Do it manually with the rules in the table above. Where you can, allow port 6661 from the main server only. The port listens on all interfaces and is protected by the API key.

How to check it worked

On the load balancer:

systemctl is-active xtreamgo-agent
journalctl -u xtreamgo-agent --no-pager -n 30
grep -E '^AGENT_(SERVER_ID|HTTP_PORT|API_PORT)=' /opt/xtreamgo-agent/.env
curl -s http://127.0.0.1/health
ss -ltnp | grep -E ':(80|8080|6661)\s'

Expected results: active, no line that starts with [Agent] Failed, the three settings, {"status":"ok"}, and listeners on port 80 (nginx), on the agent HTTP port and on 6661.

On the main server:

journalctl -u xtreamgo-db-access-sync --no-pager -n 5
systemctl is-active xtreamgo-db-forward
iptables -S XTREAMGO_DBACCESS

Expected results: a line that starts with [db-access-sync] ok and lists the load balancer IP, active, and one ACCEPT rule per load balancer IP followed by a DROP rule.

In the panel: the server shows as online on the Servers page.

To verify that streams run on the load balancer:

# on the load balancer
pgrep -a ffmpeg | head
ls /app/data/hls | head

# from any machine, with a real subscriber line and a stream assigned to the load balancer
curl -sI "http://<main-server>/live/<username>/<password>/<stream-id>.ts" | grep -iE '^(HTTP|Location)'

Expected results: ffmpeg processes for the assigned streams, one directory or file set per running stream, and a 302 answer whose Location header points at the load balancer.

If something goes wrong