IPTVBoss

IPTV playlist and EPG management with a headless XC Server

IPTVBoss manages IPTV playlists and EPG data and re-serves them through a headless Xtream Codes (XC) server. QuickBox Pro installs it as a single server-level application owned by the installing admin: an always-on XC Server (loopback-bound, reverse-proxied by nginx with per-subdomain SSL) plus a scheduled headless processing run that syncs your playlists and EPG on a systemd timer. The IPTVBoss license is user-owned - QuickBox never accepts, stores, logs, or automates any license key; you activate IPTVBoss through its own interface.

When to use it

Installation

Server-level install requires an admin

IPTVBoss is a single server-level application, so only a QuickBox admin (account level 9 or higher) can install it, and there is one install per server. The -u <adminuser> you pass records the install against that admin and homes IPTVBoss’s config and data under /home/<adminuser>/IPTVBoss. Both service units run as that admin.

QuickBox installs IPTVBoss from its beta build. The beta is the only supported build: it carries the headless XC Server and -nogui processing modes that QuickBox’s managed services depend on, which the stable build does not expose. There is therefore no stable/beta channel selector and no --beta flag for IPTVBoss - the beta build is always used.

Install from the Dashboard

Open App Dashboard -> Package Management (/dashboard?mode=packages), find IPTVBoss under the Media Servers category, and click Install. The dashboard streams the install log live and IPTVBoss appears on your App Dashboard when it finishes. Reinstall, Update, and Remove are available from the same catalog.

In the install dialog you can switch the domain toggle to Custom and enter a subdomain - the install then issues SSL and serves the XC Server endpoint on that subdomain (see The XC Server endpoint and SSL subdomain). Because IPTVBoss is server-level, install it from an admin account.

Install and manage from the CLI

The CLI runs the same install pipeline and is suited to automation and scripting. The -d domain and the DNS flags map to the dashboard choices above:

qb install iptvboss -u adminuser
qb install iptvboss -u adminuser -d iptvboss.example.com
qb install iptvboss -u adminuser -d iptvboss.example.com --dns --dns-provider cloudflare
qb reinstall iptvboss -u adminuser
qb update iptvboss -u adminuser
qb remove iptvboss -u adminuser
qb help iptvboss

Passing -d <domain> issues the Let’s Encrypt certificate and writes the subdomain nginx vhost as part of the install. Add --dns --dns-provider <provider> for a DNS-01 challenge (needed for wildcard certificates). Full flag reference: CLI Reference.

Architecture

A single IPTVBoss install runs as two systemd units with two different jobs:

The two units operate on their own copies of the IPTVBoss database, so a scheduled processing run and the XC Server run at the same time without contention - the timer does not interrupt the always-on portal.

The XC Server endpoint and SSL subdomain

The SSL subdomain is the XC Server endpoint - the address your IPTV clients and players connect to for the Xtream Codes service, and where the XC Server serves its own web-based Server Console. It is not a management page for the IPTVBoss app; you configure IPTVBoss in its desktop editor (see Licensing and the IPTVBoss editor).

Because the XC Server is root-path oriented, that endpoint is served at the root of a dedicated subdomain - for example https://iptvboss.example.com/ - not on a subpath. Attach a subdomain and QuickBox reverse-proxies the loopback XC port to it over HTTPS.

There are three ways to attach the subdomain: a single-call install (Path A), a post-install retrofit from the CLI (Path B), and the dashboard SSL Control page (Path C).

Path A - Subdomain at install time

Point a DNS record (A or CNAME) for your chosen subdomain at the server, then pass -d <domain> to the install:

qb install iptvboss -u adminuser -d iptvboss.example.com

The install issues the certificate, writes the subdomain vhost, and starts the XC Server behind it in one call - no separate lecert step required.

Path B - Retrofit a subdomain to an existing install

If IPTVBoss is already installed and you want to attach (or move) its subdomain, issue the certificate with the IPTVBoss lecert flag. The -u is required - it names the admin that owns the install:

qb install lecert --iptvboss -d iptvboss.example.com -u adminuser

This requests a Let’s Encrypt certificate (HTTP-01 challenge by default), writes the per-user subdomain vhost iptvboss.example.com reverse-proxied to the assigned XC port, reloads nginx, and registers the certificate for automatic renewal.

Wildcard or DNS challenge: add --dns --dns-provider cloudflare (or another supported provider) and use a wildcard domain such as *.example.com. See the Let’s Encrypt application reference for the full list of supported DNS providers.

Path C - Dashboard SSL Control

The dashboard’s SSL Control page at System -> SSL Control (/system/ssl) exposes the same flow. Pick IPTVBoss as the target, enter the subdomain and the owning admin username, choose the challenge method, and QuickBox runs the same qb install lecert --iptvboss pipeline under the hood. For end-to-end setup, supported DNS providers, wildcard certificates, and renewal behavior, see the SSL Certificates dashboard page.

Managing IPTVBoss from the dashboard

Open the App Dashboard (/dashboard, the default control view), find the IPTVBoss row, and expand it. The row shows the XC Server status, version, and assigned port, and its expansion carries a two-tab panel:

• XC Server - start, stop, and restart the always-on service, apply and reload it after a change, see the XC endpoint and SSL status with a link to manage the certificate, check desktop-access options, and stream the live service logs.
• Processing - run the headless processing sync on demand, enable or disable the schedule, see the last and next run with the last result, and read the recent processing log.

Because IPTVBoss is server-level infrastructure, the row and both panels are shown to admins only. Any admin can manage the install regardless of which admin ran it.

Licensing and the IPTVBoss editor

IPTVBoss’s license is user-owned. QuickBox never accepts, stores, logs, or automates any license key - activation and full configuration happen in IPTVBoss’s own editor, which is a graphical desktop application.

To reach the editor on a headless server you need a desktop remote installed for the admin account - either noVNC (in-browser) or x2go (native client). Install one of those, open a desktop session, launch IPTVBoss, and complete licensing and any source configuration there.

Scheduled processing

The processing run (the headless -nogui sync) fetches your sources, updates EPG and playlists, and writes a backup, then exits. It is driven by a systemd timer that fires daily by default and catches a run missed while the box was off.

Manage the schedule and trigger runs from the Processing tab of the IPTVBoss row on the App Dashboard:

• Run now - trigger a processing sync immediately (rejected if one is already running).
• Schedule - enable or disable the timer.
• Last run / Next run / Last result - see when processing last ran, when it runs next, and whether it succeeded.

Configuration and files

Service management

Both IPTVBoss units are static (not per-user templated). Manage them by name:

# Always-on XC Server
systemctl status iptvboss-xcserver.service
systemctl restart iptvboss-xcserver.service
journalctl -u iptvboss-xcserver.service -f
 
# Scheduled processing - the timer and its oneshot
systemctl status iptvboss-nogui.timer
systemctl list-timers iptvboss-nogui.timer
 
# Trigger a processing run by hand
systemctl start iptvboss-nogui.service
journalctl -u iptvboss-nogui.service -f

Updating IPTVBoss

IPTVBoss updates through its vendor apt source, which the install registers. Run:

qb update iptvboss -u adminuser

This upgrades the IPTVBoss package to the latest beta build, refreshes the dependency bridge, and leaves your config, data, and schedule in place. When an update is available, the IPTVBoss row on the App Dashboard shows an update pill you can act on directly.

Delete Protection

The scheduled processing unit (iptvboss-nogui.service) is a first-class Delete Protection target, so IPTVBoss is covered the moment you enable the feature. Delete Protection guards against a runaway deletion during a processing run by slowing large unlink operations.

Enable it from Settings > General > Feature Flags in the dashboard. Delete Protection is opt-in and honors your setting - it does nothing until an admin turns it on, and it then applies to IPTVBoss automatically. For per-app thresholds and the full behavior, see the Delete Protection page.

Troubleshooting

The XC Server will not start

The subdomain is not reachable

Confirm the DNS record for your subdomain points at the server, that the certificate issued (re-run the lecert step in The XC Server endpoint and SSL subdomain if it did not), and that the XC Server is running. Until a subdomain is attached the XC Server has no public endpoint - configure IPTVBoss in its desktop editor and control the service from the App Dashboard in the meantime.

Scheduled processing did not run

# Is the timer enabled and when does it next fire?
systemctl list-timers iptvboss-nogui.timer
 
# Read the last processing run's output
journalctl -u iptvboss-nogui.service -n 100

Check the Processing tab of the IPTVBoss row for the last result. If the schedule is off, enable it there. A run can also fail if the IPTVBoss editor was left open holding the main database - close it and run again.

I cannot license or configure IPTVBoss

Licensing and source configuration happen in IPTVBoss’s own graphical editor, which needs a desktop remote. Install noVNC or x2go for the admin account, open a desktop session, and launch IPTVBoss from there.

Best practices

Frequently asked questions

Related applications

Resources