CDN zones¶
When streamers stand in different cities and networks, the viewer should be sent to the near one. That is what CDN zones are for: the viewer's IP is matched to a zone by CIDR routes, and the playback balancer picks a live streamer of the matched zone that has the stream.
While no zone has a CIDR route, the default behavior applies: players are sent to the edge streamers if the cluster has any, otherwise to the streamer where the stream is ingested. For an installation in one network that is usually enough — zones arrive together with geography.
How the streamer is picked¶
- The viewer's IP is compared against the CIDR routes of all zones; the longest matching prefix wins.
- In the winning zone, a live streamer carrying the stream is looked for.
- If there is none — the viewer is taken to that zone's fallback zone, if one is set.
- From there — the streamer's delivery mode: with a public payload URL the viewer gets a redirect straight to the machine, without one central proxies the media through itself (see the streamer settings).
Create a zone¶
The CDN zones screen → Create zone, a short name like eu or nyc.
The zone editor opens:
- CIDR routes — IPv4 and IPv6 prefixes in one list:
10.0.0.0/8,2a02:6b8::/32. A chip per prefix; the form rejects an invalid CIDR. - Fallback zone — where to take the viewer when this zone has no live streamer with the stream.
Before saving the first route, assign playback streamers to zones and cover viewer IPv4 and IPv6 networks. After saving, viewers outside the routes and streamers outside the allowed zone chain cannot participate in playback. Empty zones can be prepared in advance: they do not change playback on their own.
Press Save. If the zone was edited in parallel, the editor shows the same conflict banner as the other forms: re-read or overwrite.
Assign the streamers¶
A zone without streamers routes nothing. Membership is set on the streamer's side: the CDN zone field in its settings. In the registry the zone shows next to the machine's name.
If viewers end up in the wrong place¶
- A viewer lands in someone else's zone. Check the routes: the longest prefix among all zones wins — a more specific route of another zone overrides yours.
- Viewers get central's address instead of a streamer's. The streamer has no public payload URL — central proxies the media. A working mode, but all the traffic flows through central.
Explicit routes and refusal¶
The first valid CIDR route enables restricted playback across the installation. Central selects only nodes in the matching zone and its explicit fallback_zone chain. Unzoned nodes and unrelated zones are excluded. none (null in the API), a missing zone or a repeated zone ends traversal. When no eligible target remains, central returns 503 with Retry-After; an unknown stream returns 404.
When CDN routing is enabled, requests without a matching CIDR or a client IP also fail. Configure a general route explicitly: 0.0.0.0/0 for IPv4 and ::/0 for IPv6. Empty zones do not enable CDN routing. Deleting the last CIDR route restores unrestricted selection: edge streamers first, then ingest streamers.
Origin is not a universal fallback. Viewers from one failed office could overload it and disrupt broadcasts in other offices. To allow it, assign the origin node to origin-pool, create that zone (its routes may be empty), and set the office fallback to it. The name has no special meaning. An origin in the client zone is also explicitly allowed.
| Configuration | When every office-2 node is unavailable |
|---|---|
office-2 → none |
Refusal; office-1 and origin excluded |
office-2 → office-1 → none |
Only office-1, then refusal |
office-2 → origin-pool → none |
Only origin-pool, then refusal |
Load and limits¶
Within a zone edge and ingest are equal: central selects the node with the fewest active Play sessions, distributing ties evenly. Origin has no special priority. JSON lists zones in chain order and each zone's nodes by increasing load; private addresses are excluded. Normal GET may use proxy or local delivery.
The node's CDN settings provide two independent fields:
playback_session_limit: maximum active Play sessions (Publish excluded).playback_bandwidth_kbit: outgoing traffic of the whole host in kbit/s, including internode traffic. Separate from the placement budgetnetwork_bandwidth_kbit(RX+TX).
An empty field removes the limit; 0 prevents new selection. A value at or above the limit excludes the node. If every node is excluded, central tries the next explicit zone. Missing required metrics exclude a node; the last report is usable while the node is online. Explicit limits also apply without CDN zones.
These limits govern new routing decisions in central. Delayed reports and previously issued URLs can cause overshoot. They do not shape bandwidth or terminate sessions. Players receive the updated route on their next routing request; existing URLs are not revoked.
For VOD, central first filters available placements by allowed zones, then selects the highest available revision, followed by zone and load. A newer forbidden replica cannot exclude an older permitted replica; a newer permitted fallback replica may take precedence over an older home replica.
One trusted proxy¶
Enter CIDRs under Cluster trusted proxies in the shared central settings, one prefix per line. The list applies to the entire cluster, including every central instance and streamer, with no local overrides. For example:
192.0.2.10/32
2001:db8::10/128
Only a trusted peer may supply the last IP in X-Forwarded-For. The proxy must append the actual client address. Missing or malformed headers fall back to the socket peer; X-Real-IP is ignored. An empty list trusts no headers. Multiple trusted proxy hops are not supported.
Changes and clearing the list apply automatically as configuration refreshes, without a restart. An invalid CIDR is rejected and the field shows the error. The API exposes trusted_proxies through PATCH /central/api-v4/config; an empty array or null removes trust in all proxies. The listener determines the public URL scheme.