ptp-proxy — IPTV, archivos y procesamiento multimedia IPTV, almacenamiento y nodo multimedia

ptp-proxy reúne en un único servicio la entrega de canales IPTV, el restream compartido, la transcodificación, el túnel VOD, las grabaciones y la publicación segura de archivos locales o remotos. Puede ejecutarse por sí solo o conectarse como nodo a un servidor PTP.

Modos de funcionamiento

Qué puedes construir con ptp-proxy

Las mismas funciones pueden combinarse. Un equipo puede ser a la vez proxy IPTV, servidor de archivos, nodo de transcodificación y agente remoto de PTP.

Funciones principales de un nodo

Formas de despliegue

Requisitos del sistema

Dependencias por función

Instala solo lo que necesita tu despliegue. El binario principal puede trabajar con canales y fuentes nativas sin Python ni herramientas de addons.

Notas importantes sobre FFmpeg

Instalar FFmpeg en Windows

1. Ir a gyan.dev/ffmpeg/builds y descargar la versión release-full
2. Descomprimir en, por ejemplo, C:\ffmpeg\
3. Añadir C:\ffmpeg\bin al PATH del sistema o bien copiar ffmpeg.exe a la misma carpeta que ptp-proxy.exe
4. Verificar: abrir terminal y ejecutar ffmpeg -version

Instalar FFmpeg en Linux / WSL2

sudo apt update && sudo apt install ffmpeg
# Verificar:
ffmpeg -version

¿Qué versión de FFmpeg necesito?

Verificar soporte NVENC (GPU NVIDIA)

# Debe aparecer "h264_nvenc" en la lista
ffmpeg -hide_banner -encoders | grep nvenc
# Prueba rápida — si da error, el driver no es compatible
ffmpeg -hide_banner -f lavfi -i nullsrc -t 1 -c:v h264_nvenc -f null -

Arquitectura — flujos de conexión

Los primeros diagramas explican IPTV y restream. Los flujos adicionales muestran cómo ptp-proxy publica archivos, coordina proveedores asíncronos y trabaja como nodo administrado por PTP.

1. Conexión directa — sin proxy

Los usuarios se conectan directamente al proveedor IPTV. Cada cliente abre su propio conjunto de conexiones (control, vídeo, EPG). Las credenciales del proveedor viajan en cada petición y son visibles para el cliente.

2. ptp-proxy insertado

ptp-proxy se sitúa entre los clientes y el proveedor. Los clientes solo ven la dirección del proxy. Las credenciales nunca salen del proxy. Cada cliente sigue generando su propia conexión upstream (modo proxy). Las líneas discontinuas indican flujos que el servidor puede activar o desactivar individualmente — el tráfico de control, vídeo y reproductor web puede pasar por el proxy de forma independiente.

3. Modo restream — upstream compartido

En modo restream, FFmpeg abre una sola conexión upstream por canal. Todos los clientes reciben el stream redistribuido. El proveedor ve exactamente una conexión sin importar cuántos espectadores haya.

4. Escenario VPN — proxy dentro de un túnel

Si ptp-proxy corre en un host que está dentro de una VPN (o un túnel Cloudflare, WireGuard, etc.). Todo el tráfico upstream al proveedor sale por la IP de la VPN. Los clientes se conectan normalmente al proxy desde el exterior.

5. Gateway de almacenamiento

El cliente utiliza la misma API sin conocer dónde vive el archivo. ptp-proxy conserva las credenciales, publica metadatos y traduce el seek del reproductor a rangos del origen.

6. Nodo administrado por PTP

PTP coordina varios nodos sin convertirlos en simples proxies de túnel. Cada nodo mantiene sus fuentes y plugins, y PTP conserva usuarios, catálogo y selección de ubicación.

7. Preparación asíncrona mediante plugins

La operación controla contenido que todavía no existe como archivo reproducible. Cuando termina, el resultado usa exactamente la misma API y permisos que cualquier otra fuente.

Quién conserva cada responsabilidad

Instalación en Windows

1. Descargar ptp-proxy.exe desde la sección Descargas de esta guía
2. Crear una carpeta, por ejemplo C:\ptp-proxy\
3. Copiar ptp-proxy.exe a esa carpeta
4. Copiar el archivo config.example.json a la misma carpeta y renombrarlo a config.json
5. Editar config.json con un editor de texto (Notepad++, VS Code...)
6. Abrir el terminal (cmd o PowerShell) en esa carpeta y ejecutar:

ptp-proxy.exe --config config.json

Ejecutar automáticamente al inicio (opcional)

Para que el proxy arranque automáticamente con Windows, usa el soporte de servicio integrado en el propio ejecutable (opción recomendada, sin herramientas adicionales) o bien el Programador de tareas / NSSM (alternativa).

Instalar como Servicio de Windows (recomendado)

# Instalar e iniciar el servicio
ptp-proxy.exe --install-service --config "C:\ptp-proxy\config.json"
ptp-proxy.exe --start-service
sc query ptp-proxy

# Detener y desinstalar el servicio
ptp-proxy.exe --stop-service
ptp-proxy.exe --uninstall-service

Por defecto el servicio se instala con inicio automático. Si prefieres iniciarlo a mano, añade --demand:

# Arranque manual (solo cuando se solicite)
ptp-proxy.exe --install-service --demand --config "C:\ptp-proxy\config.json"

Alternativa: NSSM

NSSM sigue siendo válido si ya lo usas para otros servicios.

# NSSM (https://nssm.cc)
nssm install PtpProxy "C:\ptp-proxy\ptp-proxy.exe" "--config C:\ptp-proxy\config.json"
nssm start PtpProxy

Diferencias Windows vs Linux

Instalación en Linux

1. Descargar el binario ptp-proxy (Linux x64) a, por ejemplo, /opt/ptp-proxy/
2. Darle permisos de ejecución:

chmod +x /opt/ptp-proxy/ptp-proxy

3. Copiar config.example.json como config.json en la misma carpeta y editar
4. Ejecutar:

cd /opt/ptp-proxy
./ptp-proxy --config config.json

Ejecutar como servicio systemd (recomendado en Linux)

Crear el archivo /etc/systemd/system/ptp-proxy.service

[Unit]
Description=ptp-proxy
After=network.target

[Service]
ExecStart=/opt/ptp-proxy/ptp-proxy --config /opt/ptp-proxy/config.json
WorkingDirectory=/opt/ptp-proxy
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now ptp-proxy
sudo systemctl status ptp-proxy
journalctl -u ptp-proxy -f

El binario es estático (no requiere nada extra)

Usar el proxy en WSL2 (Linux dentro de Windows)

Cómo funciona la red en WSL2

WSL2 tiene su propia interfaz de red, pero Windows incluye un mecanismo llamado localhost forwarding: si una aplicación dentro de WSL2 escucha en 127.0.0.1, Windows redirige automáticamente las conexiones a 127.0.0.1 del host hacia la VM.

Paso 1 — Instalar WSL2 y Ubuntu

wsl --install
wsl --install -d Ubuntu-24.04

Paso 2 — Copiar el binario a WSL2

wsl -d Ubuntu-24.04 -- bash -c "cp /mnt/c/path/ptp-proxy /home/user/ptp-proxy"
wsl -d Ubuntu-24.04 -- bash -c "chmod +x /home/user/ptp-proxy"

O acceder a WSL2 directamente y mover los archivos:

wsl
cp /mnt/c/path/to/binary/ptp-proxy ~/ptp-proxy
chmod +x ~/ptp-proxy

Paso 3 — Configurar el config.json para WSL2

La clave es hacer que el proxy escuche en 127.0.0.1 dentro de WSL2. Windows se encarga del forwarding automáticamente.

"server": {
  "listen": "127.0.0.1",   // ← IMPORTANTE: no 0.0.0.0
  "port":   8180
}

Paso 4 — Iniciar el proxy desde PowerShell

wsl -d Ubuntu-24.04 -- bash -c "cd /path/to/proxy ; nohup ./ptp-proxy > ptp-proxy.log 2>&1 &"
wsl -d Ubuntu-24.04 -- bash -c "tail -5 /path/to/proxy/ptp-proxy.log"
wsl -d Ubuntu-24.04 -- bash -c "pkill ptp-proxy"

Paso 5 — Verificar desde Windows

Invoke-WebRequest http://127.0.0.1:8180/health
curl http://127.0.0.1:8180/health

Rutas en config.json para WSL2

Puedes poner la carpeta de streams directamente en Windows para ver los archivos fácilmente:

"storage_path": "/mnt/c/path/streams/"   // carpeta de Windows accesible desde WSL2

FFmpeg en WSL2

sudo apt update && sudo apt install ffmpeg

Configuración básica (config.json)

El archivo config.json es el único fichero de configuración. Se edita con cualquier editor de texto. A continuación se explica cada bloque.

Mapa de la configuración

El archivo se divide por responsabilidad. Puedes empezar con servidor, seguridad y una sola fuente o canal, y añadir el resto después.

Estructura completa con valores por defecto

{
  // ── Servidor ──────────────────────────────────────────────
  "server": {
    "listen": "127.0.0.1",
    "port":   8180,
    "worker_threads": 0,
    "request_header_limit": 32768,
    "request_body_limit": 1048576,
    "request_timeout_sec": 30,
    "write_timeout_sec": 60,
    "keep_alive_timeout_sec": 30,
    "max_requests_per_connection": 100,
    "health_secret": "",
    "tls": {
      "enabled": false,
      "port":    8443,
      "cert":    "",
      "key":     ""
    }
  },
  // ── Logging ───────────────────────────────────────────────
  "logging": {
    "file": "ptp-proxy.log",
    "json": true
  },
  // ── Seguridad ─────────────────────────────────────────────
  "security": {
    "block_private_ips": true,
    "management_ips":   ["127.0.0.1", "::1"],
    "access_key":       "",
    "localhost_bypass": true,
    "proxy_raw_public": false,
    "key_exempt_paths": [],
    "allow_unauthenticated_remote": false,
    "allow_access_key_query": false,
    "allow_legacy_url_query": false,
    "verify_upstream_tls": false,
    "upstream_ca_file": "",
    "rate_limit": {
      "enabled":     true,
      "window_sec":  10,
      "max_requests": 300
    }
  },
  // ── FFmpeg ─────────────────────────────────────────────────
  "ffmpeg": {
    "path":             "ffmpeg",
    "hls_time_seconds": 4,
    "hls_list_size":    10,
    "extra_args":       []
  },
  // ── Transcoding profiles ───────────────────────────────────
  "transcoding": {
    "profiles_dir":            "./profiles",
    "default_profile":         "libopenh264_balanced",
    "allow_legacy_extra_args": true
  },
  // ── Restream output ────────────────────────────────────────
  "restream": {
    "output":           "disk",
    "storage_path":     "./streams/",
    "startup_grace_ms": 30000,
    "idle_timeout_sec": 120
  },
  // ── Storage sources ───────────────────────────────────────────
  "storage": {
    "sources": [
      {
        "id":        "media",
        "type":      "local",
        "root_path": "./media"
      }
    ]
  },
  // ── Core (claims integration) ─────────────────────────────────────────────────────────────
  "core": {
    "url":    "",
    "secret": ""
  },
  // ── Canales ────────────────────────────────────────────────
  "channels": []
}

Opciones de <code>server.listen</code>

Límites HTTP y capacidad

Los límites protegen frente a conexiones lentas, cuerpos descontrolados y sesiones keep-alive excesivas, manteniendo estable el servicio bajo carga.

Fuentes de almacenamiento y acceso HTTP público

Las fuentes local, WebDAV, SFTP, SMB, NFS, FTP/FTPS y catálogo HTTP comparten autorización por permisos, IDs públicos opacos, enlaces temporales, límites y reproducción con rangos.

"storage": {
  "sources": [
    {
      "id":        "media",
      "type":      "local",
      "root_path": "./media"
    }
  ]
}

TLS / HTTPS en el listener

El servidor puede escuchar en HTTP y HTTPS simultáneamente (dos puertos independientes). Se soportan TLS 1.2 y TLS 1.3; SSLv2 / SSLv3 siempre desactivados.

"server": {
  "listen": "0.0.0.0",
  "port":   8180,
  "tls": {
    "enabled": true,
    "port":    8443,
    "cert":    "/etc/letsencrypt/live/mydomain.com/fullchain.pem",
    "key":     "/etc/letsencrypt/live/mydomain.com/privkey.pem"
  }
}

Salida HLS: disco, filesystem en memoria o RAM integrada

Perfiles de transcodificación compatibles con PTP

ptp-proxy carga perfiles JSON con el mismo formato que PTP. Cada perfil tiene un identificador estable, etiquetas, códec y variantes para reproducción directa, remux y HLS.

Catálogo y perfil por defecto

Configura el directorio de perfiles y un perfil por defecto. Los paquetes oficiales incluyen perfiles de software y aceleración por hardware.

"transcoding": {
  "profiles_dir":            "./profiles",
  "default_profile":         "libopenh264_balanced",
  "allow_legacy_extra_args": true
}

Perfil y variante HLS por canal

{
  "id":      "news",
  "mode":    "restream",
  "url":     "https://origin.example/live.m3u8",
  "profile":      "h264_nvenc_web",
  "profile_mode": "hlstrans"
}

curl -H "Authorization: Bearer ACCESS_KEY" http://127.0.0.1:8180/api/transcode/profiles

Qué define un perfil

Cómo se selecciona el perfil

• Un canal puede indicar profile y profile_mode.
• Un claim dinámico puede solicitar un perfil por identificador.
• Si no se indica, se usa transcoding.default_profile.
• PTP consulta /api/transcode/profiles y solo ofrece perfiles disponibles en el nodo.
• Los argumentos heredados pueden desactivarse después de completar la migración.

Dónde se genera la salida HLS

El perfil define cómo se codifica. El modo de salida define dónde se guardan los segmentos; son decisiones independientes.

"restream": {
  "output": "memory_fs",
  "storage_path": "/dev/shm/ptp-proxy/streams"
}

Disponibilidad real del perfil

Que un archivo de perfil exista no garantiza que el equipo tenga el codificador o driver. Prueba el perfil en cada nodo y deja que PTP almacene la disponibilidad anunciada.

Perfil con aceleración por hardware

Antes de seleccionar el perfil

• Comprueba que el nodo dispone de un codificador compatible
• Prueba el perfil con una retransmisión corta antes de asignarlo en PTP
• Mantén un perfil software disponible como alternativa

Perfil incluido para NVIDIA

"profile": "h264_nvenc_web"

Selección desde PTP

PTP puede consultar /api/transcode/profiles y ofrecer únicamente los perfiles instalados en el nodo seleccionado.

Perfiles NVIDIA incluidos

Perfiles de transcodificación por software

Los perfiles software funcionan sin un codificador de vídeo dedicado. El rendimiento depende del procesador, la resolución y el número de retransmisiones simultáneas.

Perfil software recomendado

"profile": "libopenh264_balanced"

Perfiles software incluidos

Configuración de canales

Canal en modo proxy (más sencillo)

El proxy descarga la playlist del proveedor y reescribe los segmentos. No usa FFmpeg.

"channels": [
  {
    "id":      "my_channel",
    "name":    "My Channel 1",
    "mode":    "proxy",
    "url":     "http://panel.provider.com/live/USER/PASS/123.m3u8",
    "headers": []
  }
]

Canal en modo restream (con FFmpeg)

{
  "id":         "nvenc_channel",
  "mode":       "restream",
  "url":        "http://panel.provider.com/live/USER/PASS/456.m3u8",
  "profile":      "h264_nvenc_web",
  "profile_mode": "hlstrans",
  "skip_re":      true
}

Canal con headers de autenticación

{
  "id":      "auth_channel",
  "mode":    "proxy",
  "url":     "https://cdn.provider.com/live/stream.m3u8",
  "headers": [
    { "key": "Authorization", "value": "Bearer TOKEN_HERE" },
    { "key": "Referer",       "value": "https://provider.com/" }
  ]
}

Una vez configurado, el cliente accede al canal en:

http://your-server:8180/channels/my_channel/playlist.m3u8

Canales estáticos y flujos dinámicos

Integración con un core

Cuando core.url está configurado, el cliente usa un token corto. ptp-proxy lo valida con el core y recibe la URL real, el tipo de contenido y, si corresponde, el perfil solicitado. Las credenciales reales nunca se devuelven al reproductor.

Grabaciones

La API de grabaciones puede programar un canal configurado o una URL autorizada, consultar el estado y cancelar el trabajo. El resultado se guarda en el directorio configurado y no se publica automáticamente como fuente salvo que lo añadas a almacenamiento.

• Programa por hora de inicio/fin o por duración.
• Usa un nombre de salida controlado y un directorio dedicado.
• Revisa espacio libre y permisos antes de iniciar trabajos largos.
• Las grabaciones y los restreams tienen métricas separadas.

Nodo administrado por PTP

ptp-proxy puede funcionar como agente de un servidor PTP central. El nodo conserva el acceso físico a canales, archivos, perfiles y plugins, mientras PTP coordina usuarios, catálogo, exploración y reproducción.

Tres formas de usar el mismo binario

Qué puede administrar PTP

Configuración del nodo

En una instalación integrada PTP puede proporcionar estos valores mediante el entorno. En un nodo remoto se guardan en config.json y el token de incorporación se sustituye después por una credencial propia del nodo.

"managed_node": {
  "enabled": true,
  "server_url": "https://ptp.example.com",
  "node_name": "NAS home",
  "enrollment_token": "ONE_TIME_TOKEN",
  "credential_file": "./state/ptp-node.json",
  "public_url": "",
  "direct_delivery": false,
  "reverse_relay": true,
  "verify_tls": true
}

Entrega directa y relay

Almacenamiento local y remoto

ptp-proxy también es un servidor de archivos y gateway de almacenamiento. Publica carpetas locales, unidades montadas, protocolos remotos, catálogos HTTP y proveedores externos mediante la misma API de listado, metadatos y reproducción.

Cuatro formas de presentar contenido

La API pública no cambia aunque el archivo esté en el propio equipo, en un NAS, en un servicio remoto o todavía tenga que prepararse.

Inicio rápido

1. Añade una fuente en storage.sources.
2. Crea un token con storage:list y storage:read.
3. Consulta GET /api/storage.
4. Lista con /api/storage/<public_id>/list.
5. Reproduce con /storage/<public_id>/ruta.

Fuentes y modos disponibles

Elige la fuente que corresponda al servicio remoto. Los recursos ya montados pueden exponerse como carpeta o unidad, y los proveedores externos amplían la lista sin cambiar la API pública.

{
  "id": "local-media",
  "public_id": "media",
  "type": "local",
  "root_path": "D:/Media",
  "allow_list": true,
  "allow_stream": true,
  "allow_download": false
}

{
  "id": "remote-media",
  "public_id": "cloud-a91e",
  "type": "webdav",
  "base_url": "https://dav.example.test/files/user/",
  "username": "reader",
  "password": "CHANGE_ME",
  "auth_method": "any",
  "verify_tls": true,
  "allow_list": true,
  "allow_stream": true,
  "allow_download": false
}

{
  "id": "archive",
  "public_id": "archive-a91e",
  "type": "sftp",
  "base_url": "sftp://files.example.test/media/",
  "username": "reader",
  "private_key": "./keys/id_ed25519",
  "known_hosts": "./keys/known_hosts",
  "allow_list": true,
  "allow_stream": true
}

{
  "id": "nas",
  "public_id": "nas-media",
  "type": "smb",
  "base_url": "smb://nas.example.test/video/",
  "username": "reader",
  "password": "CHANGE_ME",
  "domain": "MEDIA",
  "require_signing": true,
  "require_encryption": false
}

{
  "id": "nfs-media",
  "public_id": "nfs",
  "type": "nfs",
  "server": "192.168.1.30",
  "export_path": "/exports/media",
  "remote_path": "/library",
  "version": 3,
  "uid": 1000,
  "gid": 1000
}

{
  "id": "legacy-media",
  "public_id": "ftp-media",
  "type": "ftp",
  "base_url": "ftp://ftp.example.test/media/",
  "username": "reader",
  "password": "CHANGE_ME",
  "tls_mode": "explicit",
  "verify_tls": true,
  "passive_mode": true,
  "allow_list": true,
  "allow_stream": true,
  "allow_download": false
}

{
  "id": "cdn-catalog",
  "public_id": "cdn",
  "type": "http_manifest",
  "manifest_url": "https://catalog.example.test/media.json",
  "base_url": "https://cdn.example.test/media/",
  "refresh_sec": 300,
  "max_manifest_bytes": 8388608,
  "allowed_origins": ["https://cdn.example.test"],
  "allow_list": true,
  "allow_stream": true,
  "allow_download": false
}

{
  "id": "s3-media",
  "public_id": "s3",
  "type": "plugin",
  "plugin_id": "s3-compatible",
  "backend_type": "s3",
  "plugin_config": {
    "endpoint": "https://s3.example.test",
    "bucket": "media",
    "prefix": "library/",
    "region": "us-east-1",
    "access_key": "CHANGE_ME",
    "secret_key": "CHANGE_ME",
    "path_style": true,
    "verify_tls": true
  },
  "allow_list": true,
  "allow_stream": true,
  "allow_download": false
}

Permisos, políticas y enlaces temporales

Storage tiene autorización propia. El bypass de localhost está desactivado por defecto y conocer una URL no concede acceso.

"storage": {
  "localhost_bypass": false,
  "inherit_access_key": true,
  "allow_unauthenticated_remote": false,
  "link_secret": "CHANGE_ME_WITH_A_LONG_RANDOM_SECRET",
  "access_tokens": [
    {
      "token": "CHANGE_ME_READER_TOKEN",
      "permissions": ["storage:list", "storage:read", "storage:prepare"],
      "sources": ["local-media"]
    }
  ]
}

API y reproducción

Todas las fuentes usan las mismas rutas públicas y el mismo comportamiento HTTP.

Ejemplos con curl

curl -H "Authorization: Bearer CHANGE_ME_READER_TOKEN" http://127.0.0.1:8180/api/storage

curl -H "Authorization: Bearer CHANGE_ME_READER_TOKEN" "http://127.0.0.1:8180/api/storage/media/list?path=films"

curl -I -H "Authorization: Bearer CHANGE_ME_READER_TOKEN" http://127.0.0.1:8180/storage/media/films/movie.mp4

curl -H "Authorization: Bearer CHANGE_ME_READER_TOKEN" -H "Range: bytes=1048576-2097151" http://127.0.0.1:8180/storage/media/films/movie.mp4

curl -X POST -H "Authorization: Bearer CHANGE_ME_ADMIN_TOKEN" -H "Content-Type: application/json" --data '{"source":"media","path":"films/movie.mp4","ttl_sec":300}' http://127.0.0.1:8180/api/storage/sign

Operación, métricas y diagnóstico

Límites y códigos de respuesta

ptp_storage_active_transfers
ptp_storage_bytes_total
ptp_storage_transfer_duration_seconds_count
ptp_storage_transfer_duration_seconds_sum
ptp_storage_errors_total{code="..."}
ptp_storage_cancelled_total
ptp_storage_range_requests_total
ptp_storage_limit_rejections_total{reason="..."}
ptp_storage_plugin_restarts_total{plugin="...",reason="..."}
ptp_storage_plugin_failures_total{plugin="...",code="..."}

curl -X POST -H "Authorization: Bearer CHANGE_ME_PREPARE_TOKEN" -H "Content-Type: application/json" -H "Idempotency-Key: example-1" --data '{"torrent_file":"sample.torrent"}' http://127.0.0.1:8180/api/storage/torrent/prepare

curl -H "Authorization: Bearer CHANGE_ME_PREPARE_TOKEN" http://127.0.0.1:8180/api/storage/torrent/operations/OPERATION_ID

curl -X DELETE -H "Authorization: Bearer CHANGE_ME_PREPARE_TOKEN" http://127.0.0.1:8180/api/storage/torrent/operations/OPERATION_ID

Estados de una operación asíncrona

Fuentes nativas, montadas y plugins

curl -H "Authorization: Bearer CHANGE_ME_ADMIN_TOKEN" http://127.0.0.1:8180/api/storage/plugins

curl -H "Authorization: Bearer CHANGE_ME_ADMIN_TOKEN" http://127.0.0.1:8180/api/storage/plugin-providers

curl -X POST -H "Authorization: Bearer CHANGE_ME_ADMIN_TOKEN" -H "Content-Type: application/json" --data '{}' http://127.0.0.1:8180/api/storage/plugins/s3/restart

Diagnóstico rápido

Cómo probar el proxy

1. Verificar que el servidor arranca

tail -f ptp-proxy.log
curl http://localhost:8180/health

2. Probar un canal con ffplay

curl http://localhost:8180/api/channels
ffplay http://localhost:8180/channels/my_channel/playlist.m3u8

3. Probar VOD tunnel con un token estático (sin servidor de validación)

Útil para probar el proxy sin tener un servidor de validación montado. Añadir al config.json:

"core": {
  "url": "", "secret": "",
  "static_vod_tokens": { "test": "https://your-cdn.com/movie.mkv" }
}

ffplay http://localhost:8180/stream?t=test

4. Probar con VLC

1. Abrir VLC → Medio → Abrir ubicación de red
2. Introducir: http://127.0.0.1:8180/channels/mi_canal/playlist.m3u8
3. Click en Reproducir

5. Ver métricas

curl http://localhost:8180/metrics

6. Probar el servidor de archivos

Usa un token con storage:list y storage:read. Comprueba listado, cabeceras y un rango pequeño antes de abrir un vídeo completo.

curl -H "Authorization: Bearer CHANGE_ME_LIST_TOKEN" http://localhost:8180/api/storage
curl -H "Authorization: Bearer CHANGE_ME_LIST_TOKEN" "http://localhost:8180/api/storage/media/list?path="
curl -I -H "Authorization: Bearer CHANGE_ME_READ_TOKEN" http://localhost:8180/storage/media/video.mp4
curl -H "Authorization: Bearer CHANGE_ME_READ_TOKEN" -H "Range: bytes=0-1048575" http://localhost:8180/storage/media/video.mp4

7. Comprobar perfiles de transcodificación

curl -H "Authorization: Bearer CHANGE_ME" http://localhost:8180/api/transcode/profiles

8. Comprobar un nodo administrado

En PTP verifica que el nodo aparece conectado, publica fuentes y perfiles y puede completar un trabajo de listado. En el proxy revisa que el heartbeat no exponga secretos.

9. Ejecutar la suite automatizada

La suite crea servicios simulados locales y comprueba almacenamiento, seguridad, plugins, TLS, CONNECT, perfiles y operaciones asíncronas sin depender de proveedores reales.

cmake -S . -B build-tests -DPTP_BUILD_STORAGE_TESTS=ON
cmake --build build-tests
ctest --test-dir build-tests --output-on-failure
python3 tests/run_all.py

Solución de problemas comunes

Leer los logs

El proxy genera logs estructurados y censura tokens, firmas, nonces, URLs y cabeceras sensibles. Los mensajes de stream muestran solo el origen upstream.

{"lvl":"INFO", "msg":"[stream] type=live mode=hls_proxy upstream=http://cdn:80"}
{"lvl":"WARN", "msg":"proxy_claim HTTP 403: Forbidden IP"}
{"lvl":"ERROR","msg":"ffmpeg exited with code 1"}

Campos de log importantes

Qué observar según la función

Métricas útiles

• ptp_storage_active_transfers y bytes transferidos.
• Duración, cancelaciones, rangos y rechazos por límite.
• Reinicios y fallos de plugins.
• Restreams y grabaciones activas.
• Tiempo de actividad y errores HTTP.

Seguir logs en tiempo real

tail -f ptp-proxy.log
# Con formato legible (requiere jq):
tail -f ptp-proxy.log | jq -r '.lvl + " | " + .msg'

Seguridad — Capas de protección

El proxy combina protecciones HTTP generales con permisos específicos para streams, almacenamiento, plugins, CONNECT y nodos administrados. No todas las rutas usan la misma credencial ni el mismo alcance.

Capa 1 — Rate limiting (anti-hammering)

Limita cuántas peticiones puede hacer una IP en una ventana de tiempo. Si se supera, devuelve 429 Too Many Requests.

"rate_limit": {
  "enabled":     true,
  "window_sec":  10,
  "max_requests": 60
}

Capa 2 — IPs de administración

Los endpoints sensibles (/metrics, /api/*, /proxy/raw) solo son accesibles desde las IPs listadas.

"management_ips": ["127.0.0.1", "::1"]

Capa 3 — Access key

Con access_key configurado, los endpoints protegidos requieren Authorization: Bearer. El query ?key= solo funciona si se activa expresamente allow_access_key_query.

# Header HTTP (curl, backends):
curl -H "Authorization: Bearer MY_KEY" http://proxy:8180/channels/my_channel/playlist.m3u8

Configuración de producción recomendada

"security": {
  "block_private_ips": true,
  "management_ips":   ["127.0.0.1", "::1"],
  "access_key":       "long-random-key-here",
  "localhost_bypass": true,
  "allow_unauthenticated_remote": false,
  "allow_access_key_query": false,
  "allow_legacy_url_query": false,
  "verify_upstream_tls": false,
  "rate_limit": { "enabled": true, "window_sec": 10, "max_requests": 300 }
}

Superficies y credenciales

Protecciones adicionales

• SSRF sin doble resolución DNS: se conecta a los mismos endpoints que fueron validados.
• Cada redirección se vuelve a validar contra la política SSRF y allow_hosts.
• Las playlists usan contextos opacos; URL y headers upstream permanecen en memoria del servidor.
• Los secretos y URLs sensibles se censuran en logs; los mensajes de stream solo muestran el origen.
• Los nonces de /health no pueden reutilizarse y la caché está limitada a 65.536 entradas.
• La verificación TLS saliente es opcional y está desactivada por defecto; puede activarse con verify_upstream_tls.

Checklist de exposición remota

• Usa TLS o un reverse proxy seguro.
• Configura una clave larga y desactiva compatibilidad por query.
• Limita IPs de administración.
• Mantén la verificación TLS de orígenes cuando sea posible.
• Define tokens de almacenamiento por permiso y fuente.
• Configura límites globales, por IP y por fuente.
• No publiques endpoints de control de addons.
• Prueba la revocación de nodos y enlaces temporales.
• Revisa periódicamente logs, métricas e integridad de plugins.

Sistema claim — Autenticación segura de tokens

¿Por qué es necesario?

Sin un sistema de autenticación, cualquier persona que conozca la URL del proxy podría:

• Adivinar o reutilizar tokens de otros usuarios
• Hacer que el proxy acceda a URLs que tú no autorizaste (SSRF)
• Usar el proxy como relay abierto para sus propias peticiones

El sistema claim resuelve esto: el proxy nunca confía en el token del cliente directamente. Siempre verifica con tu servidor de validación que ese token es válido y autentica la propia petición de verificación con una firma HMAC.

El flujo completo para un cliente IPTV

El cliente nunca ve las credenciales reales. Solo ve http://proxy:8180/stream?t=TOKEN.

Por qué es seguro

Cálculo del claim HMAC — Paso a paso

Este apartado explica exactamente cómo el proxy construye el claim que envía a tu servidor de validación. Si quieres implementar tu propio servidor de validación (en cualquier lenguaje), esto es todo lo que necesitas.

Ingredientes del claim

Fórmula exacta

// 1. Construir el mensaje concatenando con "|"
message = token + "|" + ts + "|" + nonce

// Ejemplo concreto:
//   token = "e3df09b42ad23f8174eaf28bbe9ad96b"
//   ts    = 1740698753
//   nonce = "a3f9c2b1d8e04f72"
message = "e3df09b42ad23f8174eaf28bbe9ad96b|1740698753|a3f9c2b1d8e04f72"

// 2. Firmar con HMAC-SHA256 usando el secreto compartido:
sig = HMAC-SHA256(secret, message)  →  resultado en hex minúsculas

JSON que el proxy envía a tu servidor

POST https://your-php.com/api.php?proxy_claim=1
Content-Type: application/json

{
  "token": "e3df09b42ad23f8174eaf28bbe9ad96b",
  "ts":    1740698753,
  "nonce": "a3f9c2b1d8e04f72",
  "sig":   "2b9f3e7d1c45a8f2..."   // 64 hex chars
}

Respuesta que tu servidor debe devolver

// Token válido:
{ "ok": true, "url": "http://panel/live/USER/PASS/123.m3u8", "type": "live" }
// Token inválido:
{ "ok": false, "error": "Token not found" }

Tipos de stream soportados en la respuesta

Implementar tu propio servidor de claims

Si quieres construir tu propia integración, aquí tienes implementaciones de referencia en varios lenguajes.

<?php
// ── Endpoint: api.php?proxy_claim=1 ───────────────────────────────────────────
if (isset($_GET['proxy_claim'])) {
    $body  = json_decode(file_get_contents('php://input'), true);
    $token = $body['token'] ?? null;
    $ts    = $body['ts']    ?? null;
    $nonce = $body['nonce'] ?? null;
    $sig   = $body['sig']   ?? null;
    if (!$token || !$ts || !$nonce || !$sig) {
        http_response_code(400);
        echo json_encode(['ok' => false, 'error' => 'Missing fields']);
        exit;
    }
    // Verificar HMAC — el secreto NO viaja nunca en la petición
    $secret   = 'YOUR_SHARED_SECRET_HERE';
    $msg      = $token . '|' . $ts . '|' . $nonce;
    $expected = hash_hmac('sha256', $msg, $secret);
    // hash_equals hash_equals evita timing attacks
    if (!hash_equals($expected, $sig)) {
        echo json_encode(['ok' => false, 'error' => 'Invalid signature']);
        exit;
    }
    // Anti-replay: rechazar timestamps viejos (±5 min)
    if (abs(time() - (int)$ts) > 300) {
        echo json_encode(['ok' => false, 'error' => 'Timestamp expired']);
        exit;
    }
    $info = buscar_token_en_db($token);  // tu función aquí
    if (!$info) {
        echo json_encode(['ok' => false, 'error' => 'Token not found']);
        exit;
    }
    echo json_encode(['ok' => true, 'type' => $info['type'], 'url' => $info['url']]);
}

import hmac, hashlib, time, json
from flask import Flask, request, jsonify
app = Flask(__name__)
SECRET = 'YOUR_SHARED_SECRET_HERE'

@app.route('/api', methods=['POST'])
def proxy_claim():
    if request.args.get('proxy_claim') != '1':
        return jsonify({'ok': False}), 404
    body  = request.get_json()
    token, ts, nonce, sig = body.get('token'), body.get('ts'), body.get('nonce'), body.get('sig')
    if not all([token, ts, nonce, sig]):
        return jsonify({'ok': False, 'error': 'Missing fields'})
    msg      = f"{token}|{ts}|{nonce}"
    expected = hmac.new(SECRET.encode(), msg.encode(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, sig):
        return jsonify({'ok': False, 'error': 'Invalid signature'})
    if abs(time.time() - int(ts)) > 300:
        return jsonify({'ok': False, 'error': 'Timestamp expired'})
    info = buscar_token(token)
    if not info: return jsonify({'ok': False, 'error': 'Token not found'})
    return jsonify({'ok': True, 'type': info['type'], 'url': info['url']})

const crypto  = require('crypto');
const express = require('express');
const app     = express();
app.use(express.json());
const SECRET = 'YOUR_SHARED_SECRET_HERE';

app.post('/api', (req, res) => {
    if (req.query.proxy_claim !== '1') return res.status(404).end();
    const { token, ts, nonce, sig } = req.body;
    if (!token || !ts || !nonce || !sig) return res.json({ ok: false, error: 'Missing fields' });
    const msg      = `${token}|${ts}|${nonce}`;
    const expected = crypto.createHmac('sha256', SECRET).update(msg).digest('hex');
    const a = Buffer.from(sig, 'utf8'), b = Buffer.from(expected, 'utf8');
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b))
        return res.json({ ok: false, error: 'Invalid signature' });
    if (Math.abs(Date.now() / 1000 - +ts) > 300)
        return res.json({ ok: false, error: 'Timestamp expired' });
    const info = findToken(token);
    if (!info) return res.json({ ok: false, error: 'Token not found' });
    res.json({ ok: true, type: info.type, url: info.url });
});

package main
import (
    "crypto/hmac"; "crypto/sha256"; "crypto/subtle"
    "encoding/hex"; "encoding/json"; "fmt"; "math"; "net/http"; "time"
)
const secret = "YOUR_SHARED_SECRET_HERE"

type ClaimBody struct {
    Token string `json:"token"`
    Ts    int64  `json:"ts"`
    Nonce string `json:"nonce"`
    Sig   string `json:"sig"`
}
func proxyClaim(w http.ResponseWriter, r *http.Request) {
    var b ClaimBody
    json.NewDecoder(r.Body).Decode(&b)
    msg := fmt.Sprintf("%s|%d|%s", b.Token, b.Ts, b.Nonce)
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(msg))
    expected := hex.EncodeToString(mac.Sum(nil))
    if subtle.ConstantTimeCompare([]byte(expected), []byte(b.Sig)) != 1 {
        json.NewEncoder(w).Encode(map[string]interface{}{"ok": false, "error": "Invalid signature"})
        return
    }
    if math.Abs(float64(time.Now().Unix()-b.Ts)) > 300 {
        json.NewEncoder(w).Encode(map[string]interface{}{"ok": false, "error": "Timestamp expired"})
        return
    }
    json.NewEncoder(w).Encode(map[string]interface{}{
        "ok": true, "type": "live", "url": "http://panel/live/USER/PASS/123.m3u8",
    })
}

Proxy CONNECT — Tunelizar tráfico saliente a través de ptp-proxy

Además del sistema de claims para los clientes IPTV, el proxy incluye un handler para peticiones HTTP CONNECT. Esto permite que cualquier cliente HTTP (curl, tu app web, u otro servicio) tunelice sus conexiones salientes a través de ptp-proxy, de forma que todo el tráfico salga por la interfaz de red del host donde corre ptp-proxy — independientemente del sistema operativo. Un caso de uso habitual es enrutar las peticiones de tu servicio a través de un host o red diferente.

Configuración en config.json

"connect_proxy": {
  "enabled":         true,
  "use_claim":       false,
  "secret":          "YOUR_SECRET_HERE",
  "allowed_origins": ["127.0.0.1", "::1"],
  "allowed_hosts":   []
}

Dos modos de autenticación para CONNECT

Modo A — Secreto estático (<code>use_claim: false</code>)

El cliente envía el secreto directamente en cada petición. Más simple. Recomendado cuando el cliente y el proxy están en el mismo host.

function curl_set_ptp_proxy_static(CurlHandle $ch): void {
    curl_setopt($ch, CURLOPT_PROXY,       'http://127.0.0.1:8180');
    curl_setopt($ch, CURLOPT_PROXYTYPE,   CURLPROTO_HTTP);
    curl_setopt($ch, CURLOPT_PROXYHEADER, ['X-Proxy-Secret: YOUR_SECRET_HERE']);
}

Modo B — Claim HMAC (<code>use_claim: true</code>)

El cliente firma cada petición CONNECT con HMAC. El secreto nunca viaja en claro. Necesario si el proxy está expuesto a internet.

function curl_set_ptp_proxy_claim(CurlHandle $ch, string $url): void {
    $parsed = parse_url($url);
    $host   = $parsed['host'];
    $port   = $parsed['port'] ?? ($parsed['scheme'] === 'https' ? 443 : 80);
    $ts    = time();
    $nonce = bin2hex(random_bytes(8));
    $msg   = "connect|{$host}:{$port}|{$ts}|{$nonce}";
    $sig   = hash_hmac('sha256', $msg, 'YOUR_SECRET_HERE');
    curl_setopt($ch, CURLOPT_PROXY,       'http://127.0.0.1:8180');
    curl_setopt($ch, CURLOPT_PROXYTYPE,   CURLPROTO_HTTP);
    curl_setopt($ch, CURLOPT_PROXYHEADER, [
        "X-Proxy-Ts: {$ts}",
        "X-Proxy-Nonce: {$nonce}",
        "X-Proxy-Sig: {$sig}",
    ]);
}

Fórmula del claim HMAC para CONNECT

message = "connect" + "|" + host + ":" + port + "|" + ts + "|" + nonce
sig     = HMAC-SHA256(secret, message)  →  hex minúsculas
Ejemplo:  message = "connect|api.provider.com:443|1740698753|a3f9c2b1d8e04f72"
  sig     = hash_hmac('sha256', message, secret)

Exponer a internet con seguridad total

Si tu servicio está en un servidor remoto, necesitas que el proxy acepte conexiones desde internet. Con use_claim: true esto es seguro:

"connect_proxy": {
  "enabled":         true,
  "use_claim":       true,
  "secret":          "random-key-minimum-32-chars",
  "allowed_origins": [],
  "allowed_hosts":   ["api.provider1.com", "api.provider2.com"]
}

Generar un secreto seguro

# Linux / WSL2:
openssl rand -hex 32

Referencia de endpoints HTTP

Referencia pública de canales, VOD, grabaciones, perfiles, almacenamiento y administración. Las rutas de contenido, gestión y permisos de almacenamiento tienen políticas diferentes.

Referencia rápida con curl

# Listar canales
curl -H "Authorization: Bearer CHANGE_ME" http://127.0.0.1:8180/api/channels
# Listar fuentes de almacenamiento
curl -H "Authorization: Bearer CHANGE_ME_LIST_TOKEN" http://127.0.0.1:8180/api/storage
# Leer un rango de un archivo
curl -H "Authorization: Bearer CHANGE_ME_READ_TOKEN" -H "Range: bytes=0-1048575" http://127.0.0.1:8180/storage/media/films/movie.mkv
# Consultar perfiles
curl -H "Authorization: Bearer CHANGE_ME" http://127.0.0.1:8180/api/transcode/profiles
# Consultar plugins
curl -H "Authorization: Bearer CHANGE_ME_ADMIN_TOKEN" http://127.0.0.1:8180/api/storage/plugins
# Iniciar una preparación
curl -X POST -H "Authorization: Bearer CHANGE_ME_PREPARE_TOKEN" -H "Content-Type: application/json" --data '{"torrent_file":"sample.torrent"}' http://127.0.0.1:8180/api/storage/torrent/prepare