ptp-proxy — IPTV, files and media processing IPTV, storage and managed media node

ptp-proxy combines IPTV delivery, shared restreaming, transcoding, VOD tunnelling, recordings and secure publication of local or remote files in one service. It can run by itself or connect to a PTP server as a managed node.

Operating modes

What you can build with ptp-proxy

The same features can be combined. One machine may simultaneously act as an IPTV proxy, file server, transcoding edge and remote PTP agent.

Main roles of a node

Deployment models

System requirements

Dependencies by feature

Install only what your deployment needs. The main binary can serve channels and native sources without Python or addon tools.

Important notes about FFmpeg

Install FFmpeg on Windows

1. Go to gyan.dev/ffmpeg/builds and download the release-full build
2. Extract to e.g. C:\ffmpeg\
3. Add C:\ffmpeg\bin to the system PATH or copy ffmpeg.exe to the same folder as ptp-proxy.exe
4. Verify: open a terminal and run ffmpeg -version

Install FFmpeg on Linux / WSL2

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

Which FFmpeg version do I need?

Verify NVENC support (NVIDIA GPU)

# Should show "h264_nvenc" in the list
ffmpeg -hide_banner -encoders | grep nvenc
# Quick test — if it errors, the driver is not compatible
ffmpeg -hide_banner -f lavfi -i nullsrc -t 1 -c:v h264_nvenc -f null -

Architecture — connection flows

The first diagrams explain IPTV and restreaming. Additional flows show how ptp-proxy publishes files, coordinates asynchronous providers and works as a PTP-managed node.

1. Direct connection — no proxy

Users connect directly to the IPTV provider. Every client opens its own set of connections (control, video, EPG). Provider credentials travel in every request and are visible to the client.

2. ptp-proxy inserted

ptp-proxy sits between clients and the provider. Clients only see the proxy address. Credentials never leave the proxy. Each client still generates its own upstream connection (proxy mode). Dashed lines indicate flows that the server can individually enable or disable — control, video and web-player traffic can each be proxied or bypassed independently.

3. Restream mode — shared upstream

In restream mode, FFmpeg opens one upstream connection per channel. All clients receive the re-distributed stream. The provider sees exactly one connection regardless of how many viewers there are.

4. VPN scenario — proxy inside a tunnel

If ptp-proxy runs on a host that sits inside a VPN (or a Cloudflare tunnel, WireGuard, etc.). All upstream traffic to the provider exits through the VPN IP. Clients connect to ptp-proxy normally from the outside.

5. Storage gateway

The client uses the same API without knowing where the file lives. ptp-proxy keeps credentials, publishes metadata and translates player seek into origin ranges.

6. PTP-managed node

PTP coordinates multiple nodes without treating them as generic tunnel proxies. Each node keeps its sources and plugins while PTP owns users, catalogue and location selection.

7. Asynchronous plugin preparation

The operation controls content that is not yet a playable object. When it completes, the result uses the same API and permissions as any other source.

Responsibility boundaries

Installation on Windows

1. Download ptp-proxy.exe from the Downloads section of this guide
2. Create a folder, e.g. C:\ptp-proxy\
3. Copy ptp-proxy.exe into that folder
4. Copy config.example.json to the same folder and rename it to config.json
5. Edit config.json with a text editor (Notepad++, VS Code...)
6. Open a terminal (cmd or PowerShell) in that folder and run:

ptp-proxy.exe --config config.json

Run automatically on startup (optional)

To have the proxy start automatically with Windows, use the built-in service support (recommended — no extra tools needed) or Task Scheduler / NSSM (alternative).

Install as a Windows Service (recommended)

# Install and start the service
ptp-proxy.exe --install-service --config "C:\ptp-proxy\config.json"
ptp-proxy.exe --start-service
sc query ptp-proxy

# Stop and uninstall the service
ptp-proxy.exe --stop-service
ptp-proxy.exe --uninstall-service

By default the service is installed with automatic startup. If you prefer to start it manually, add --demand:

# Manual start (only when explicitly requested)
ptp-proxy.exe --install-service --demand --config "C:\ptp-proxy\config.json"

Alternative: NSSM

NSSM is still valid if you already use it for other services.

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

Windows vs Linux differences

Installation on Linux

1. Download the binary ptp-proxy (Linux x64) to e.g. /opt/ptp-proxy/
2. Grant execute permission:

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

3. Copy config.example.json as config.json in the same folder and edit it
4. Run:

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

Run as a systemd service (recommended on Linux)

Create the file /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

The binary is static (no extra dependencies)

Using the proxy on WSL2 (Linux inside Windows)

How WSL2 networking works

WSL2 has its own network interface, but Windows includes a mechanism called localhost forwarding: if an application inside WSL2 listens on 127.0.0.1, Windows automatically redirects connections to the host's 127.0.0.1 to the VM.

Step 1 — Install WSL2 and Ubuntu

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

Step 2 — Copy the binary to 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"

Or access WSL2 directly and move the files:

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

Step 3 — Configure config.json for WSL2

The key is to make the proxy listen on 127.0.0.1 inside WSL2. Windows handles the forwarding automatically.

"server": {
  "listen": "127.0.0.1",   // ← IMPORTANT: not 0.0.0.0
  "port":   8180
}

Step 4 — Start the proxy from 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"

Step 5 — Verify from Windows

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

Paths in config.json for WSL2

You can put the streams folder directly in Windows to easily see the files:

"storage_path": "/mnt/c/path/streams/"   // Windows folder accessible from WSL2

FFmpeg in WSL2

sudo apt update && sudo apt install ffmpeg

Basic configuration (config.json)

The config.json file is the only configuration file. Edit it with any text editor. Each block is explained below.

Configuration map

The file is split by responsibility. Start with server, security and one source or channel, then add the remaining blocks as needed.

Full structure with default values

{
  // ── Server ──────────────────────────────────────────────
  "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
  },
  // ── Security ─────────────────────────────────────────────
  "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": ""
  },
  // ── Channels ────────────────────────────────────────────────
  "channels": []
}

<code>server.listen</code> options

HTTP limits and capacity

The limits protect against slow connections, unbounded bodies and excessive keep-alive sessions, keeping the service stable under load.

Storage sources and public HTTP access

Local, WebDAV, SFTP, SMB, NFS, FTP/FTPS and HTTP catalog sources share scoped authorization, opaque public IDs, temporary links, limits and ranged playback.

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

TLS / HTTPS on the listener

The server can listen on HTTP and HTTPS simultaneously (two independent ports). TLS 1.2 and TLS 1.3 are supported; SSLv2 / SSLv3 are always disabled.

"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"
  }
}

HLS output: disk, memory filesystem or integrated RAM

PTP-compatible transcoding profiles

ptp-proxy loads JSON profiles using the same format as PTP. Each profile has a stable identifier, labels, codec metadata and variants for direct playback, remuxing and HLS.

Catalogue and default profile

Configure the profile directory and a default profile. Official packages include software and hardware-accelerated options.

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

Per-channel profile and HLS variant

{
  "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

What a profile defines

How the profile is selected

• A channel may set profile and profile_mode.
• A dynamic claim may request a profile by identifier.
• When omitted, transcoding.default_profile is used.
• PTP queries /api/transcode/profiles and only offers profiles available on the node.
• Legacy arguments may be disabled after migration is complete.

Where HLS output is generated

The profile defines encoding. The output mode defines where segments are stored; these are independent choices.

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

Actual profile availability

A profile file does not guarantee that the encoder or driver exists on the machine. Test every profile on each node and let PTP store the availability announced by that node.

Hardware-accelerated profile

Before selecting the profile

• Confirm that the node exposes a compatible encoder
• Test the profile with a short restream before assigning it in PTP
• Keep a software profile available as a fallback choice

Included NVIDIA profile

"profile": "h264_nvenc_web"

Selection from PTP

PTP can query /api/transcode/profiles and offer only profiles installed on the selected node.

Included NVIDIA profiles

Software transcoding profiles

Software profiles work without a dedicated video encoder. Performance depends on the processor, resolution and number of concurrent restreams.

Recommended software profile

"profile": "libopenh264_balanced"

Included software profiles

Channel configuration

Channel in proxy mode (simplest)

The proxy downloads the provider's playlist and rewrites the segments. Does not use FFmpeg.

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

Channel in restream mode (with 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
}

Channel with authentication headers

{
  "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/" }
  ]
}

Once configured, the client accesses the channel at:

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

Static channels and dynamic flows

Core integration

When core.url is configured, the client uses a short token. ptp-proxy validates it with the core and receives the real URL, content type and, where relevant, requested profile. Origin credentials are never returned to the player.

Recordings

The recording API can schedule a configured channel or authorised URL, query status and cancel the job. The result is written to the configured directory and is not automatically exposed as a storage source unless you add it.

• Schedule by start/end time or duration.
• Use a controlled output name and dedicated directory.
• Check free space and permissions before long jobs.
• Recordings and restreams have separate metrics.

PTP-managed node

ptp-proxy can act as an agent of a central PTP server. The node keeps physical access to channels, files, profiles and plugins while PTP coordinates users, catalogue, browsing and playback.

Three ways to use the same binary

What PTP can manage

Node configuration

In an integrated installation PTP may provide these values through the environment. On a remote node they are stored in config.json; after enrollment the one-time token is replaced by a node-specific credential.

"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
}

Direct delivery and relay

Local and remote storage

ptp-proxy is also a file server and storage gateway. It publishes local folders, mounted drives, remote protocols, HTTP catalogues and external providers through the same listing, metadata and playback API.

Four ways to present content

The public API does not change whether the file is on the same machine, on a NAS, on a remote service or still needs to be prepared.

Quick start

1. Add a source to storage.sources.
2. Create a token with storage:list and storage:read.
3. Request GET /api/storage.
4. Browse with /api/storage/<public_id>/list.
5. Play with /storage/<public_id>/path.

Sources and available modes

Choose the source matching the remote service. Resources already mounted can be exposed as a directory or drive, while external providers add new services without changing the public API.

{
  "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
}

Permissions, policies and temporary links

Storage has its own authorization layer. Localhost bypass is disabled by default and knowing a URL does not grant access.

"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 and playback

Every source uses the same public paths and HTTP behaviour.

curl examples

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

Operations, metrics and troubleshooting

Limits and response codes

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

Asynchronous operation states

Native, mounted and plugin sources

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

Quick troubleshooting

How to test the proxy

1. Verify the server starts

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

2. Test a channel with ffplay

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

3. Test VOD tunnel with a static token (no validation server)

Useful for testing the proxy without a validation server set up. Add to config.json:

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

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

4. Test with VLC

1. Open VLC → Media → Open Network Stream
2. Enter: http://127.0.0.1:8180/channels/my_channel/playlist.m3u8
3. Click Play

5. View metrics

curl http://localhost:8180/metrics

6. Test the file server

Use a token with storage:list and storage:read. Test listing, headers and a small range before opening a complete video.

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. Check transcoding profiles

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

8. Check a managed node

In PTP, verify that the node is connected, publishes sources and profiles and can complete a listing job. In the proxy logs, verify that heartbeat messages expose no secrets.

9. Run the automated suite

The suite creates local simulated services and verifies storage, security, plugins, TLS, CONNECT, profiles and asynchronous operations without relying on real providers.

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

Common troubleshooting

Reading logs

The proxy produces structured logs and redacts tokens, signatures, nonces, URLs and sensitive headers. Stream messages only show the upstream origin.

{"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"}

Important log fields

What to watch by feature

Useful metrics

• ptp_storage_active_transfers and transferred bytes.
• Duration, cancellations, ranges and limit rejections.
• Plugin restarts and failures.
• Active restreams and recordings.
• Uptime and HTTP errors.

Follow logs in real time

tail -f ptp-proxy.log
# Readable format (requires jq):
tail -f ptp-proxy.log | jq -r '.lvl + " | " + .msg'

Security — Protection layers

The proxy combines general HTTP protections with specialised permissions for streams, storage, plugins, CONNECT and managed nodes. Not every route uses the same credential or scope.

Layer 1 — Rate limiting (anti-hammering)

Limits how many requests an IP can make in a time window. If exceeded, returns 429 Too Many Requests.

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

Layer 2 — Management IPs

Sensitive endpoints (/metrics, /api/*, /proxy/raw) are only accessible from the listed IPs.

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

Layer 3 — Access key

When access_key is configured, protected endpoints require Authorization: Bearer. The ?key= query is accepted only when allow_access_key_query is explicitly enabled.

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

Recommended production configuration

"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 }
}

Surfaces and credentials

Additional protections

• SSRF without a second DNS lookup: connections use the exact endpoints that were validated.
• Every redirect is revalidated against the SSRF policy and allow_hosts.
• Playlists use opaque contexts; upstream URLs and headers remain in server memory.
• Secrets and sensitive URLs are redacted from logs; stream messages show only the upstream origin.
• /health nonces cannot be reused and the cache is bounded to 65,536 entries.
• Outbound TLS verification is optional and disabled by default; enable it with verify_upstream_tls.

Remote-exposure checklist

• Use TLS or a secure reverse proxy.
• Configure a long key and disable query-string compatibility.
• Restrict management IPs.
• Keep origin TLS verification enabled where possible.
• Create storage tokens by permission and source.
• Set global, per-IP and per-source limits.
• Do not publish addon control endpoints.
• Test node revocation and temporary-link expiry.
• Review logs, metrics and plugin integrity regularly.

Claim system — Secure token authentication

Why is it needed?

Without an authentication system, anyone who knows the proxy URL could:

• Guess or reuse tokens from other users
• Force the proxy to access URLs you didn't authorize (SSRF)
• Use the proxy as an open relay for their own requests

The claim system solves this: the proxy never trusts the client's token directly. It always verifies with your validation server that the token is valid, and authenticates the verification request itself with an HMAC signature.

The full flow for an IPTV client

The client never sees the real credentials. It only sees http://proxy:8180/stream?t=TOKEN.

Why it is secure

HMAC claim calculation — Step by step

This section explains exactly how the proxy builds the claim it sends to your validation server. If you want to implement your own validation server (in any language), this is all you need.

Claim ingredients

Exact formula

// 1. Build the message by concatenating with "|"
message = token + "|" + ts + "|" + nonce

// Concrete example:
//   token = "e3df09b42ad23f8174eaf28bbe9ad96b"
//   ts    = 1740698753
//   nonce = "a3f9c2b1d8e04f72"
message = "e3df09b42ad23f8174eaf28bbe9ad96b|1740698753|a3f9c2b1d8e04f72"

// 2. Sign with HMAC-SHA256 using the shared secret:
sig = HMAC-SHA256(secret, message)  →  result in lowercase hex

JSON the proxy sends to your server

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
}

Response your server must return

// Valid token:
{ "ok": true, "url": "http://panel/live/USER/PASS/123.m3u8", "type": "live" }
// Invalid token:
{ "ok": false, "error": "Token not found" }

Stream types supported in the response

Implement your own claims server

If you want to build your own integration, here are reference implementations in several languages.

<?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;
    }
    // Verify HMAC — the secret NEVER travels in the request
    $secret   = 'YOUR_SHARED_SECRET_HERE';
    $msg      = $token . '|' . $ts . '|' . $nonce;
    $expected = hash_hmac('sha256', $msg, $secret);
    // hash_equals hash_equals prevents timing attacks
    if (!hash_equals($expected, $sig)) {
        echo json_encode(['ok' => false, 'error' => 'Invalid signature']);
        exit;
    }
    // Anti-replay: reject old timestamps (±5 min)
    if (abs(time() - (int)$ts) > 300) {
        echo json_encode(['ok' => false, 'error' => 'Timestamp expired']);
        exit;
    }
    $info = buscar_token_en_db($token);  // your function here
    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",
    })
}

CONNECT proxy — Tunnel outgoing traffic through ptp-proxy

In addition to the claims system for IPTV clients, the proxy includes a handler for HTTP CONNECT requests. This allows any HTTP client (curl, your web app, or any service) to tunnel its outgoing connections through ptp-proxy, so all traffic exits through the network interface of the machine where ptp-proxy is running — regardless of OS. A typical use case is routing your service's requests through a different host or network.

Configuration in config.json

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

Two authentication modes for CONNECT

Mode A — Static secret (<code>use_claim: false</code>)

The client sends the secret directly in each request. Simpler. Recommended when the client and the proxy are on the same 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']);
}

Mode B — HMAC claim (<code>use_claim: true</code>)

The client signs each CONNECT request with HMAC. The secret never travels in plaintext. Required if the proxy is exposed to the 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}",
    ]);
}

HMAC claim formula for CONNECT

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

Safely exposing to the internet

If your service is on a remote server, you need the proxy to accept connections from the internet. With use_claim: true this is safe:

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

Generate a secure secret

# Linux / WSL2:
openssl rand -hex 32

API Endpoint Reference

Public reference for channels, VOD, recordings, profiles, storage and administration. Content routes, management routes and storage scopes follow different policies.

curl quick reference

# List channels
curl -H "Authorization: Bearer CHANGE_ME" http://127.0.0.1:8180/api/channels
# List storage sources
curl -H "Authorization: Bearer CHANGE_ME_LIST_TOKEN" http://127.0.0.1:8180/api/storage
# Read a file range
curl -H "Authorization: Bearer CHANGE_ME_READ_TOKEN" -H "Range: bytes=0-1048575" http://127.0.0.1:8180/storage/media/films/movie.mkv
# Inspect profiles
curl -H "Authorization: Bearer CHANGE_ME" http://127.0.0.1:8180/api/transcode/profiles
# Inspect plugins
curl -H "Authorization: Bearer CHANGE_ME_ADMIN_TOKEN" http://127.0.0.1:8180/api/storage/plugins
# Start preparation
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