Documentation

Overview

Xtream Shield is a control plane and data plane system for IPTV infrastructure. It replaces legacy panel software with a modern, Go-native architecture designed for stability at scale.

The system is composed of a stateless control plane (user management, configuration, health orchestration) and a stateful data plane (stream ingestion, transcoding, segment delivery). These communicate over authenticated internal channels.

Installation

Xtream Shield ships as a single static binary. No runtime dependencies.

# Download latest release
wget https://releases.xtream-shield.com/v2.4.1/xtream-shield-linux-amd64
chmod +x xtream-shield-linux-amd64
mv xtream-shield-linux-amd64 /usr/local/bin/xtream-shield

# Create configuration directory
mkdir -p /etc/xtream-shield

# Generate initial config
xtream-shield --init-config > /etc/xtream-shield/config.yaml

# Start the control plane
xtream-shield --config /etc/xtream-shield/config.yaml --mode control

Configuration

Core settings are managed via YAML. Sensitive values can be loaded from environment variables.

control_plane:
  bind_addr: "0.0.0.0:8080"
  tls:
    cert_file: "/etc/xtream-shield/tls.crt"
    key_file: "/etc/xtream-shield/tls.key"

 database:
  driver: "postgres"
  dsn: "${DATABASE_DSN}"

streaming:
  token_secret: "${TOKEN_SECRET}"
  segment_duration: "6s"
  max_bitrate: "8000k"

health:
  probe_interval: "10s"
  degraded_threshold: "500ms"
  fail_threshold: "3"

Control Plane

The control plane exposes the administrative API, manages user and reseller hierarchies, assigns load balancers, and orchestrates health checks across the data plane.

• • Stateless — can be scaled horizontally behind a load balancer
• • All configuration persisted to the database
• • Pushes configuration deltas to data plane nodes

Data Plane

The data plane runs on edge nodes close to your audience. It ingests source streams via RTMP or HLS, transcodes to adaptive bitrates, generates segments, and serves clients.

• • Runs FFmpeg with resource limits and watchdog monitoring
• • Validates tokens in-memory without database access
• • Reports health metrics back to control plane every 10s

Authentication

All API requests require a valid bearer token. Stream requests use HMAC-signed playback tokens.

POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "..."
}

Response:
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2026-04-24T12:00:00Z"
}