Repository navigation
Support Sources and Operations
This page is for operators: keeping chosen streams running with nobody watching, and monitoring a running daemon.
A support source is a live stream that Outpace keeps open and seeds to other peers even when no local viewer is watching. Use it to:
- run a node that helps distribute particular public channels;
- keep a channel warm so the first viewer starts instantly.
The support pin works like an invisible viewer. Real viewers and HLS clients join the same download and share its session slot.
export OUTPACE_SUPPORT_SOURCES='{"relay1":"0123456789abcdef0123456789abcdef01234567"}'
outpace serveThe value is a JSON object mapping a name of your choice to a live selector: a content id, an
ih: infohash with a verified descriptor, or a transport-file URL.
- At most 8 entries and 64 KiB.
- Names are 1–64 ASCII letters, digits,
_or-. Selectors are at most 4096 bytes. - Don't put credentials in names.
-
Requires
OUTPACE_ENABLE_INBOUNDandOUTPACE_ENABLE_SEEDINGto be on. Outpace won't turn them on for you; startup fails instead. - Not compatible with private peer mode.
- VOD, protected content, and transport URLs on private or loopback addresses are rejected.
- Sources start after all listeners are up.
| Request | Effect |
|---|---|
GET /support |
Lists each declaration: name, desired and observed state, reason, attempts, bytes emitted, retry delay. It never shows selectors. |
POST /support/<name>/stop |
Stops supporting that source. Real viewers keep watching. |
POST /support/<name>/start |
Starts it again, or restarts it after a terminal error. |
curl http://127.0.0.1:6878/support
curl -X POST http://127.0.0.1:6878/support/relay1/stop
curl -X POST http://127.0.0.1:6878/support/relay1/start- POST bodies must be empty.
- A
202means the command was accepted. PollGET /supportto see it take effect. - Unknown names return
404. You can't create declarations over HTTP. -
DELETE /streams/ace/<id>on a supported stream also disables its support, so it isn't immediately restarted. Usestartto re-enable it. - API start and stop aren't saved. A restart applies the declarations from the environment again.
| Event | What happens |
|---|---|
| Network, discovery or admission failure | Retries after 1, 2, 4, 8 and 16 seconds, then every 30 seconds. The backoff resets after 30 seconds of real progress. |
| The source ends normally | A fresh run starts. Direct TS viewers see the stream end and reconnect. HLS viewers get a closed playlist (ENDLIST) and must reopen the URL. |
| Invalid, unsafe or protected descriptor | Stops with an error until you start it again. |
OUTPACE_MAX_SESSIONS reached |
Waits and retries. Existing streams stay joinable. |
None of these start a stream. Use them for monitoring, never a playback URL.
| Endpoint | Shows | Avail. |
|---|---|---|
GET /healthz |
ok while the HTTP server runs. Liveness only: it doesn't prove peers or media. |
all |
GET /networks |
Provider networks, normally {"networks":["ace"]}. |
all |
GET /streams |
Active streams with their viewer count and metadata. | all |
GET /streams/ace/<id>/status |
One stream: start phase and error, peers, bitrate, server buffer, upload, recovery counters, session occupancy, and network_path (direct or proxy, see Outbound Proxy). While starting, or shortly after a failed start, only phase, error, clients, peers and network_path. 404 when neither running nor recently started. |
all |
GET /origin-hls/status |
Managed-relay state: {"enabled":...,"active_sessions":...}. |
all |
GET /support |
Support-source states. | all |
GET /network-policy |
Public or private peer mode and allowlist size. The proxy object (from 1.2.0) shows the outbound proxy mode and current path. |
all |
GET /debug/memstats |
Allocator counters (live heap, resident) on 64-bit Linux and macOS builds. | all |
GET /metrics |
Prometheus text metrics. Only when OUTPACE_METRICS=1, otherwise 404. |
all |
GET /server/api?method=get_status |
dl or idle, plus active_sessions, occupied_sessions and max_sessions. Needs compat on. |
all |
GET /server/api?method=get_version |
Outpace version. Needs compat on. | all |
The provided Compose file health-checks /healthz every 10 seconds.
Set OUTPACE_METRICS=1 to serve GET /metrics in the Prometheus text format on the normal HTTP
bind. It is off by default. The endpoint has no authentication, so keep OUTPACE_BIND on a
trusted network or put it behind your reverse proxy.
At most two scrapes collect metrics at the same time, and each has two seconds to finish. A scrape
over either limit gets 503 Service Unavailable with Retry-After: 1 and an empty body, which
Prometheus records as a failed scrape (up is 0) rather than partial values. A normal
scrape_interval from one or two Prometheus servers never hits these limits.
scrape_configs:
- job_name: outpace
static_configs:
- targets: ["outpace:6878"]Labels never contain content ids, infohashes, stream or broadcast names. Per-stream values are
summed for each provider network, and HTTP series use the route template (for example
/streams/{network}/{id}/status), not the requested path.
| Metric | Type | Meaning |
|---|---|---|
outpace_build_info{version} |
gauge | Always 1, labelled with the running version. |
outpace_uptime_seconds |
gauge | Seconds since the HTTP server started. |
outpace_allocator_bytes{kind} |
gauge | jemalloc allocated, active, resident, retained, mapped. Absent on builds without jemalloc. |
outpace_admission_occupied |
gauge | Admitted sources, including pending opens. |
outpace_admission_limit |
gauge |
OUTPACE_MAX_SESSIONS. Absent when unlimited. |
outpace_sessions{network} |
gauge | Active stream sessions. |
outpace_subscribers{network} |
gauge | Clients attached to those sessions. |
outpace_peers{network} |
gauge | Connected swarm peers. |
outpace_peers_served{network} |
gauge | Distinct peers served at least one chunk. |
outpace_active_upstreams{network} |
gauge | Peers currently admitted as download upstreams. |
outpace_download_bytes_per_second{network} |
gauge | Download rate. |
outpace_upload_bytes_per_second{network} |
gauge | Upload rate. |
outpace_session_downloaded_bytes{network} |
gauge | Bytes downloaded by active sessions. |
outpace_session_uploaded_bytes{network} |
gauge | Bytes uploaded by active sessions. |
outpace_session_upstream_reconnects{network} |
gauge | Upstream reconnects in active sessions. |
outpace_session_stale_teardowns{network} |
gauge | Stale upstream teardowns in active sessions. |
outpace_session_skipped_evicted_gaps{network} |
gauge | Evicted gaps skipped in active sessions. |
outpace_session_signature_rejects{network} |
gauge | Chunks rejected for bad signatures in active sessions. |
outpace_http_requests_total{route,method,status} |
counter | HTTP requests that matched a route. Methods outside the standard set are reported as other. |
outpace_http_response_header_seconds_total{route,method,status} |
counter | Total time until response headers were sent. |
The outpace_session_* values only cover sessions that are still running, so they go down when a
stream stops. Treat them as gauges, not as process-lifetime counters. For streamed responses
(MPEG-TS, HLS segments) the HTTP timing stops at the response headers, not at the end of the
transfer. Divide it by outpace_http_requests_total for the mean.
With OUTPACE_MAX_SESSIONS set, stream status and get_status report occupied_sessions and
max_sessions (null when unlimited). Occupancy includes streams that are still starting, and
ones still cleaning up. A slot can stay busy briefly after a stream stops. When the cap is
reached, the log shows [manager] session capacity reached: occupied=… max=…, and new
streams get 503 with Retry-After: 1.
Before a planned restart, check that /streams is empty, /origin-hls/status shows
active_sessions: 0 and no broadcast is being fed. Relay viewers don't appear in /streams.
Outpace logs to standard error, one event per line, prefixed with the UTC time of day and a
[tag]. See Troubleshooting for what the tags mean. With
Compose the logs are rotated (3 × 10 MB).
This wiki is generated from docs/wiki/ in the main repository. To fix or improve a page, open a pull request there; the wiki is republished automatically when it merges, and edits made in the wiki web UI are overwritten.
Start
Watching
Publishing and peers
- Broadcasting
- Seeding and Peers
- Engine Camouflage
- NAT and Port Mapping
- Private Peer Mode
- Outbound Proxy
Running it
- Deployment
- Routers and Small Devices
- Migrating from AceStream Engine
- Support Sources and Operations
- Troubleshooting
- Releases and Versions
Success stories