XC Server Runtime Configuration¶
IPTVBoss Pro
XC Server requires Pro.
Use this reference after choosing an installation method. For the first database and player connection, follow First XC Server Connection.
Recommended command¶
The recommended command for a host using Caddy or another HTTPS reverse proxy is:
This command:
- starts XC Server mode;
- expects HTTPS to be terminated by a reverse proxy;
- binds IPTVBoss to
127.0.0.1, so it is not directly reachable from the network.
The default XC Server port is 8001. The platform setup pages explain how to install IPTVBoss, run this command under a service manager, and configure the reverse proxy:
XC Server flags¶
| Flag | Meaning |
|---|---|
-xcserver |
Start IPTVBoss as a headless XC Server. This is required for the server process. |
-xc-proxy |
Indicate that HTTPS is terminated by a reverse proxy. IPTVBoss expects requests to arrive with forwarded HTTPS information and does not use a local keystore. |
-httpsOnly |
Enable direct HTTPS instead of HTTP when no reverse proxy is being used. Direct HTTPS requires the PKCS#12 file keystore.p12 in the IPTVBoss data directory and IPTVBOSS_XC_KEYSTORE_PASSWORD. Proxy mode takes precedence when both are enabled. |
-xc-bind-address loopback |
Listen only on 127.0.0.1. This is the recommended value when using an HTTPS reverse proxy. |
-xc-bind-address all |
Listen on 0.0.0.0, allowing connections through the host’s network interfaces. Use only when the firewall and transport security are configured appropriately. |
-xc-port PORT |
Listen on TCP port PORT instead of the persisted/default port. Valid values are 1 through 65535. |
-directory PATH |
Store the IPTVBoss database, configuration, logs, keystore, and generated files under PATH instead of the operating-system default. The service account must be able to read and write this location. |
-xc-reset-admin |
Reset the XC administrator identity for the next server load. Stop the XC Server first; the command requires an interactive terminal and the exact confirmation RESET XC ADMIN. |
The bind address also accepts the equivalent literal addresses 127.0.0.1 and 0.0.0.0.
Data and port defaults¶
Unless -directory is supplied, IPTVBoss uses a per-user data directory:
| Platform | Default data directory |
|---|---|
| Linux and other Unix systems | $HOME/IPTVBoss |
| macOS | ~/Library/Application Support/IPTVBoss |
| Windows | %USERPROFILE%/IPTVBoss |
The XC Server listens on port 8001 by default. The listener port can be
configured in IPTVBoss settings or overridden for a headless process with
-xc-port PORT or IPTVBOSS_XC_PORT=PORT. The command-line value takes
precedence over the environment variable. When neither override is supplied,
the persisted port is used, including the existing server_info.json value
when present.
Listener selection¶
The effective listener is selected in this order:
-xc-bind-address, when supplied on the command line;IPTVBOSS_XC_BIND_ADDRESS, when set;- the persisted Block direct connections server setting.
The environment variable and command-line option accept loopback, all, 127.0.0.1, or 0.0.0.0.
The port has its own independent selection order:
-xc-port, when supplied;IPTVBOSS_XC_PORT, when set;- the persisted XC Server port;
- the default
8001.
For example:
An explicit port must be a TCP port from 1 through 65535. Invalid external
values prevent XC Server startup instead of silently falling back.
Example using the environment variable:
HTTPS modes¶
HTTPS reverse proxy¶
Use proxy mode when Caddy, Nginx, or another trusted reverse proxy provides HTTPS:
Proxy mode can also be enabled with:
The proxy must forward HTTPS requests and preserve the appropriate forwarded headers. IPTVBOSS_XC_TRUSTED_PROXIES can restrict which proxy addresses are allowed to provide forwarded client information; see Proxy trust.
Direct HTTP¶
Direct HTTP is the default when neither proxy mode nor HTTPS-only mode is enabled:
Use this only for an isolated local network or temporary bootstrap. Credentials, sessions, and other traffic are not encrypted.
Direct HTTPS¶
Direct HTTPS requires a PKCS#12 keystore named keystore.p12 in the selected IPTVBoss data directory and its password in the environment:
IPTVBOSS_XC_KEYSTORE_PASSWORD='change-this-password' \
iptvboss -xcserver -httpsOnly -xc-bind-address all
The environment variable IPTVBOSS_HTTPS_ONLY=true enables the same mode. Do not put the keystore password directly in a shared service file when the service manager provides a safer secret mechanism.
The keystore contains the HTTPS private key and certificate chain. Its password does not protect XC users, administrator credentials, or the database. See Direct HTTPS for certificate creation, deployment, verification, and renewal instructions.
XC Server environment variables¶
| Variable | Meaning |
|---|---|
IPTVBOSS_XC_PORT |
Select the XC listener TCP port when the command line does not specify -xc-port. |
IPTVBOSS_XC_BIND_ADDRESS |
Select loopback or all when the command line does not specify -xc-bind-address. |
IPTVBOSS_XC_BEHIND_HTTPS_PROXY |
Set to true to enable HTTPS reverse-proxy mode without -xc-proxy. |
IPTVBOSS_HTTPS_ONLY |
Set to true to require direct HTTPS without -httpsOnly. |
IPTVBOSS_XC_KEYSTORE_PASSWORD |
Password that unlocks keystore.p12 in direct HTTPS mode. It is unused in proxy and direct-HTTP modes. |
IPTVBOSS_XC_TRUSTED_PROXIES |
Optional comma-separated list of trusted proxy IP addresses or CIDRs. When set in proxy mode, forwarded client information is accepted only from those addresses. |
Boolean variables use true to enable the corresponding behavior. Proxy mode takes precedence over direct HTTPS mode, so a process configured for both expects HTTPS from the reverse proxy rather than loading the local keystore.
Proxy trust¶
Proxy mode requires the request to arrive with forwarded HTTPS information. With no trusted-proxy list, proxy requests are accepted from the peer that connects to IPTVBoss. Set IPTVBOSS_XC_TRUSTED_PROXIES when you want an explicit allowlist:
Use the actual address or CIDR of the reverse proxy as seen by IPTVBoss. Do not list arbitrary public networks.