srs/proxy/docs/proxy-protocol.md

Protocol

Backend Server Registration

The origin server can register itself to the proxy server, so the proxy server can load balance the backend servers.

Default Backend Server (For Debugging)

The proxy can automatically register a default backend server for testing and debugging purposes, controlled by environment variables:

# Enable default backend server
PROXY_DEFAULT_BACKEND_ENABLED=on

# Default backend server configuration
PROXY_DEFAULT_BACKEND_IP=127.0.0.1
PROXY_DEFAULT_BACKEND_RTMP=1935
PROXY_DEFAULT_BACKEND_HTTP=8080       # Optional
PROXY_DEFAULT_BACKEND_API=1985        # Optional
PROXY_DEFAULT_BACKEND_RTC=8000        # Optional (UDP)
PROXY_DEFAULT_BACKEND_SRT=10080       # Optional (UDP)

When enabled, the proxy automatically registers this default backend server at startup and sends heartbeats every 30 seconds to keep it alive. This is useful for:

• Quick testing without setting up backend server registration
• Development and debugging scenarios
• Single-server deployments

Automatic Registration

SRS 5.0+ has built-in support for automatic registration to the proxy server using the heartbeat feature. Configure SRS to send heartbeats to the proxy's System API:

# For example, conf/origin1-for-proxy.conf in SRS.
heartbeat {
    enabled on;
    interval 9;
    url http://127.0.0.1:12025/api/v1/srs/register;
    device_id origin1;
    ports on;
}

When heartbeat is enabled:

• SRS automatically registers itself on startup
• Sends periodic heartbeats (default: every 30 seconds) to keep the registration alive
• Proxy marks servers as unavailable if heartbeats stop (after 300 seconds)
• No manual intervention required - fully automatic

This is the recommended approach for production deployments with SRS backend servers.

Manual Registration API

For non-SRS backend servers or custom integrations, use the HTTP API directly:

curl -X POST http://127.0.0.1:12025/api/v1/srs/register \
     -H "Connection: Close" \
     -H "Content-Type: application/json" \
     -H "User-Agent: curl" \
     -d '{
          "device_id": "origin2",
          "ip": "10.78.122.184",
          "server": "vid-46p14mm",
          "service": "z2s3w865",
          "pid": "42583",
          "rtmp": ["19352"],
          "http": ["8082"],
          "api": ["19853"],
          "srt": ["10082"],
          "rtc": ["udp://0.0.0.0:8001"]
        }'
#{"code":0,"pid":"53783"}

Registration Fields

• ip: Mandatory, the IP of the backend server. Make sure the proxy server can access the backend server via this IP.
• server: Mandatory, the server id of backend server. For SRS, it stores in file, may not change.
• service: Mandatory, the service id of backend server. For SRS, it always changes when restarted.
• pid: Mandatory, the process id of backend server. Used to identify whether process restarted.
• rtmp: Mandatory, the RTMP listen endpoints of backend server. Proxy server will connect backend server via this port for RTMP protocol.
• http: Optional, the HTTP listen endpoints of backend server. Proxy server will connect backend server via this port for HTTP-FLV or HTTP-TS protocol.
• api: Optional, the HTTP API listen endpoints of backend server. Proxy server will connect backend server via this port for HTTP-API, such as WHIP and WHEP.
• srt: Optional, the SRT listen endpoints of backend server. Proxy server will connect backend server via this port for SRT protocol.
• rtc: Optional, the WebRTC listen endpoints of backend server. Proxy server will connect backend server via this port for WebRTC protocol.
• device_id: Optional, the device id of backend server. Used as a label for the backend server.

Listen Endpoint Format

The listen endpoint format is port, or protocol://ip:port, or protocol://:port, for example:

• 1935: Listen on port 1935 and any IP for TCP protocol.
• tcp://:1935: Listen on port 1935 and any IP for TCP protocol.
• tcp://0.0.0.0:1935: Listen on port 1935 and any IP for TCP protocol.
• tcp://192.168.3.10:1935: Listen on port 1935 and specified IP for TCP protocol.

Integration Options Summary

There are three ways to register backend servers to the proxy:

1. Automatic Registration (Recommended for Production)

   • Use SRS 5.0+ with heartbeat feature
   • Fully automatic, no manual scripts needed
   • Self-healing: automatically re-registers if proxy restarts
   • See "Automatic Registration (SRS 5.0+ Heartbeat)" section above

2. Manual Registration API

   • For non-SRS media servers (nginx-rtmp, Node-Media-Server, etc.)
   • Requires custom registration script or service
   • More flexible for heterogeneous environments
   • See "Manual Registration API" section above

3. Default Backend (Development/Testing Only)

   • Quick setup via environment variables
   • No backend server configuration needed
   • Use for development, testing, and debugging
   • See "Default Backend Server (For Debugging)" section above