XC_VM/docs/en/info/faq.md

FAQ - Frequently Asked Questions

Here you will find answers to the most common questions and issues when working with XC_VM.

---

Stream Issues

❌ My stream doesn’t start on MAIN or LB

---

Diagnostics

Connect to your server console and run the following command:

sudo -u xc_vm /home/xc_vm/console.php monitor 291

🧩 Where 291 is your stream ID (replace it with your own).

---

What the command does

The monitor command tries to start the stream manually and displays an error if it fails.

---

Possible causes

1️⃣ Missing system libraries

If the output contains an error like:

error while loading shared libraries: libxyz.so.1: cannot open shared object file

Install the missing library with:

sudo apt install <library_name>

After installation, rerun the test.

💬 Let me know if a library needs to be added to the installation script.

---

2️⃣ Error not related to libraries

If the error is of another type — send its output so I can help diagnose it.

---

Summary

1. Run the diagnostic command.
2. Check for any errors.
3. Install missing libraries if necessary.
4. Report any other errors for further analysis.

---

❌ Streaming fails with "IP_MISMATCH" or "TOKEN_EXPIRED"

---

These are security features, not bugs:

• TOKEN_EXPIRED — session token has a time limit. The user needs to re-authenticate.
• IP_MISMATCH — the user's IP changed mid-stream (often detected as credential sharing).

Relevant settings:

• restrict_same_ip — how strict IP matching is
• disallow_2nd_ip_con — block simultaneous connections from different IPs

If this causes issues for legitimate users (e.g., mobile networks frequently rotating IPs), adjust the restriction level in admin panel settings.

---

---

Login & Access Issues

❌ I'm locked out — IP keeps getting blocked

---

XC_VM's brute-force guard blocks IPs after too many failed login attempts. This is controlled by:

• bruteforce_mac_attempts — attempts per MAC per time window
• bruteforce_username_attempts — attempts per username per time window
• flood_limit — total requests per window

To unblock yourself:

1. From admin panel: Tools → IP Management → remove from blocked list.
2. From CLI: sudo /home/xc_vm/console.php tools flush — flushes all blocked IPs.
3. If completely locked out: Use console.php tools rescue to create a rescue access code (see CLI Tools).

---

❌ Set-top box gets blocked after a reset/firmware change (its serial or device_id changed, but the panel has the old one)

---

A box that used to work starts getting its IP blocked after a factory reset, firmware change/update, hardware swap (or moving the MAC to a different box): it now reports a different serial number (sn) or device_id than what the panel has stored. On get_profile the server blocks the IP and the portal returns 404.

This is not a bug — it's the portal's anti-clone protection, MAGSCAN. It requires a serial number and compares the posted sn against the stored mag_devices.sn:

• No serial number in the request → ban ([MS] No Serial Number).
• Posted sn ≠ the device's stored sn → ban ([MS] Invalid Serial Number).

In both cases the IP is written to the blocked_ips table (and from there into iptables) and the device gets a 404. If the device has the lock_device flag set, device_id, device_id2 and hw_version are checked too — a mismatch fails verification and the device shows "your device is not active" (without an IP ban).

How to fix (for a legitimate box whose data genuinely changed):

1. Reset the binding in the panel: open that MAG device in admin and clear its stored serial number / device_id (or delete and re-add the device). The "serial already recorded" condition then no longer triggers, and the next connection binds the new values.
2. Unblock the IP. Easiest way — via the web panel: open Tools → IP Management (/<admin-code>/ips), which lists the blocked IPs — remove the one you need (or clear the whole list). CLI / manual options if you can't reach the panel:
   • CLI (clear all blocks): sudo /home/xc_vm/console.php tools flush;
   • Manually, per IP: sudo iptables -D INPUT -s <IP> -j DROP && sudo rm -f /home/xc_vm/tmp/flood/block_<IP>.

⚠️ The enable_debug_stalker setting bypasses the lock_device / image checks but NOT the MAGSCAN serial hard-ban (which runs earlier) — you still have to clear the stored sn in the panel.

---

❌ Forgot admin password / can't log in at all

---

Create a new rescue admin user via CLI:

sudo /home/xc_vm/console.php tools user

This outputs a random username and password with full admin privileges. Log in, change the password, and delete the rescue user when done.

If the admin panel URL itself is unknown, create a rescue access code:

sudo /home/xc_vm/console.php tools rescue

---

---

Database & Configuration

❌ "Couldn't connect to database" on startup

---

The most common issue. Causes:

1. Wrong credentials in config.ini — check host, port, db_user, db_pass, db_name
2. MySQL/MariaDB not running — sudo systemctl status mariadb
3. Network unreachable — DB server on another host and port is firewalled
4. User lacks privileges — re-grant with console.php tools mysql

Fix: Edit /home/xc_vm/config/config.ini, then run:

sudo /home/xc_vm/console.php status

---

❌ Database migration fails during update

---

Migration .sql files from migrations/ run automatically during updates. If one fails:

• The migration is recorded with [WARN] status — it won't retry automatically.
• Common causes: syntax error, table already exists, foreign key conflict, missing ALTER privilege.

Debug:

1. Check which migration failed in the console output.
2. Open the file in migrations/ and inspect the SQL.
3. Fix the issue manually in MySQL, then the next update will continue from where it stopped.

See Database Migrations for details.

---

---

SSL & Nginx

❌ SSL certificate generation fails

---

console.php certbot can fail with different error codes:

Error	Cause	Fix
Error 3	Domain is a bare IP address	Certbot requires a domain name, not an IP
Error 4	Dry run failed — port 80/443 in use	Stop conflicting service: sudo lsof -i :80
Error 0	Files not found after generation	Check /home/xc_vm/bin/certbot/logs/xc_vm.log
Error 2	Unexpected certbot error	Check logs, ensure DNS resolves to your server

Also: Remove stale lock files if certbot was interrupted:

sudo rm -f /home/xc_vm/bin/certbot/*/.certbot.lock

---

❌ Nginx won't reload — port conflicts

---

XC_VM runs two nginx instances:

1. nginx (bin/nginx/) — HTTP(S) traffic
2. nginx_rtmp (bin/nginx_rtmp/) — RTMP streaming

Each can fail if its port is already in use.

Diagnose:

sudo netstat -tlnp | grep -E ':80|:443|:1935'

Fix: Change the broadcast port in admin panel settings, then regenerate configs:

sudo /home/xc_vm/console.php tools ports

---

---

Updates & Service

❌ Update download fails or checksum mismatch

---

The update system downloads from GitHub releases. If it fails:

• Network/firewall blocks access to GitHub
• Partial download — connection dropped mid-way
• MD5 mismatch — corrupted file (update is safely aborted)

Updates are never applied if the checksum doesn't match. Re-run the update after fixing network issues:

sudo -u xc_vm /home/xc_vm/console.php update update

---

❌ Service stops unexpectedly or won't stop cleanly

---

The service command uses escalating kill signals. If processes hang:

# Check for stuck processes
ps -u xc_vm

# Force kill if necessary
sudo killall -9 -u xc_vm

# Restart cleanly
sudo /home/xc_vm/console.php service start

Common causes: PHP transaction deadlock, infinite loop in stream processing, or network socket timeout waiting for a response.

---

---

Permissions & System

❌ Permission denied errors keep reappearing

---

Run the status command — it automatically repairs all known permission issues:

sudo /home/xc_vm/console.php status

What it fixes:

• PHP-FPM socket permissions (bin/php/sockets/*)
• Content directory ownership (content/streams/)
• Config file ownership (config/)
• Executable bit on daemons.sh
• Network interface permissions (/sys/class/net)

If permissions break after every restart, check that the xc_vm system user exists and owns /home/xc_vm.

---

❌ Load Balancer shows as offline / can't sync with MAIN

---

LB servers poll MAIN via HTTP and process signals. When sync fails:

1. Network: LB can't reach MAIN's HTTP port — check firewall rules
2. Database: LB can't connect to MAIN's MySQL — re-grant privileges:

   sudo /home/xc_vm/console.php tools mysql
   

3. Timeout: If last_check_ago exceeds 180 seconds, server is marked offline

Debug: Run on MAIN to check connectivity:

sudo -u xc_vm /home/xc_vm/console.php watchdog

---

---

📘 This page is updated over time. If you discover a new common issue — please suggest it in Issues.

---