Intranet CDN¶

Intranet CDN in Agora delivers streams to remote offices and corporate network segments where broadcasting straight from the central origin would overload slow or expensive links.

In this mode Agora does not send the viewer straight to the central origin but to the appropriate restreamer inside their network zone. The same stream is delivered to the remote site once, then served locally via the restreamer.

How CDN works in Agora¶

Corporate CDN uses these entities:

• origin streamers — nodes where the stream is ingested or produced in Agora;
• restreamer — distribution node that pulls from origin and serves viewers in its zone;
• zone — logical corporate network area, often a remote office;
• CIDR routes — rules mapping the viewer’s IP to a zone;
• fallback zone — backup zone used when the primary zone has no available restreamers.

The viewer opens the stream in the browser. Agora determines the client IP, finds the matching zone, picks an available restreamer with the lowest current load in that zone, and returns a playback address.

If the zone has no available restreamers, Agora uses the fallback zone. If the client IP matches no route, CDN routing does not apply for that client.

When administrators configure CDN¶

Configure CDN when:

• you have many viewers and a single origin cannot serve them all;
• staff watch the same live feeds from remote branches;
• the link between HQ and a branch is slow or costly;
• you need fewer simultaneous connections to the central origin;
• IP ranges must map to local distribution nodes.

Prerequisites¶

Before CDN setup, prepare:

• at least one working origin streamer with the stream already available;
• at least one server to register as restreamer;
• branch or office network ranges in CIDR form, e.g. 10.20.30.0/24;
• a public-facing playback base URL per restreamer for viewers, e.g. https://edge-1.office.example;
• optionally a fallback zone for failover.

Before CDN, confirm origin streamers appear under Streamers and are healthy.

Recommended setup order¶

Suggested order:

1. Configure origin streamers.
2. Create zones.
3. Configure zone CIDR routes.
4. Set fallback zones where needed.
5. Configure restreamers.
6. Assign restreamers to zones.
7. Verify restreamer external configuration delivery.
8. Test the viewer portal from the right network.

This order reduces mistakes from empty zones, missing playback URLs, and wrong client routing.

Streams section: stream list¶

Streams are created and edited under Streams in the left menu. For CDN you need at least one stream on origin that viewers open through the viewer portal and balancer. See Streams for stream configuration.

Creating a zone¶

A zone represents an office, branch, or network segment where viewers should be served by a local restreamer.

In the zone card an administrator sets:

• name;
• fallback zone if a backup is required;
• the list of CIDR routes;
• “Skip streamer liveness check” (skip_streamer_healthcheck in the API): when enabled, the built-in balancer, when routing into this zone, picks a restreamer without requiring fresh stats or a successful edge healthcheck. Disabled (disabled) restreamers still never participate. The fallback zone has its own setting. Intended for lab CDN tests only, not production with real viewers.

The zone name should be unique and clear, for example:

• msk-office-1;
• spb-office;
• plant-a;
• vpn-users.

The fallback zone is used when the primary zone has no available restreamer.

The card screenshot shows a zone with a saved CIDR, no fallback zone, and “Skip streamer liveness check” enabled for lab testing.

Configuring CIDR routes¶

Zone routes use CIDR notation.

In the admin API each route is sent as address (string — IPv4 network address in dot notation, e.g. 10.0.0.0) and mask (integer — prefix length as in CIDR: 24 for /24). Internal storage may differ; at the API boundary the address is always a dotted string. A value like 10.0.0.0/24 in the admin UI maps to that field pair.

Valid route examples:

• 10.12.13.0/24;
• 10.12.0.0/16;
• 192.168.100.0/24;
• 0.0.0.0/0.

Agora matches the viewer IP against routes in all zones and picks the longest prefix match, so more specific rules win over broader ones.

For example:

• zone Office-A has 10.12.0.0/16;
• zone Office-A-floor-3 has 10.12.13.0/24.

A viewer at 10.12.13.42 maps to Office-A-floor-3 because /24 is more specific than /16.

If the same CIDR is already used in another zone, move or remove it from the old zone. A route must not belong to multiple zones at once.

0.0.0.0/0 is the default route. Without it, a client that matches no route gets no restreamer and no playback.

Configuring a fallback zone¶

Use a fallback zone when all restreamers in the primary zone are unavailable or disabled.

When configuring fallback:

• pick a fallback zone the site can actually reach;
• avoid circular fallback chains;
• keep the design simple for operations.

Typical example:

• zone office-ekb has a primary local restreamer;
• zone office-msk is the fallback zone for office-ekb.

If the local restreamer in office-ekb is down, viewers in that zone receive the stream via office-msk.

Configuring a restreamer¶

A restreamer is created in the same streamers section as a normal streamer, with node type restreamer.

The restreamer card includes:

• hostname;
• node type restreamer;
• connection scheme HTTP or HTTPS;
• API port;
• zone;
• playback_base_url.

playback_base_url is the URL Agora returns to viewers for playback — usually the restreamer’s external URL on the corporate or user network, e.g. https://edge-1.office.example.

A restreamer must be bound to a zone. Each restreamer belongs to exactly one zone.

What the restreamer receives from Agora¶

Like other streamers, a restreamer pulls configuration via config_external. In the CDN scenario Agora serves on-demand configuration for stream distribution.

That means:

• the stream on the restreamer is not started until a viewer requests it;
• the restreamer ingests from origin as m4s;
• publication on the restreamer starts on the first client request.

This lowers steady-state load and avoids keeping every possible stream active at once.

How Agora picks a restreamer for a viewer¶

When a viewer requests a stream, Agora:

1. Determines the client IP.
2. Finds a zone by CIDR.
3. Lists available restreamers in the zone.
4. Drops disabled and unavailable nodes.
5. Chooses the restreamer with the fewest current clients.
6. Returns a playback URL on that restreamer to the viewer portal.

“Available” restreamers are those that:

• are not disabled in the admin UI;
• pass healthcheck as healthy;
• have up-to-date operational statistics.

If “Skip streamer liveness check” is enabled for the zone, that selection step for that zone ignores healthcheck and freshness requirements: every zone-bound restreamer except admin-disabled ones is a candidate. When following a fallback chain, the target zone’s settings apply again.

Debugging CDN: source_ip query parameter¶

To test balancer and viewer portal routing from a workstation outside the target corporate subnet, add source_ip to the portal page URL: Agora treats the given IPv4 or IPv6 as the “viewer address” and applies CIDR routing as if the request came from that IP. The portal forwards the same parameter to balancer/streams/{stream}; the viewer API token is forwarded when required.

Typical lab workflow with skip_streamer_healthcheck:

• enable “Skip streamer liveness check” on zones under test so you are not blocked on live stats or healthcheck;
• enter the correct CIDR routes for those zones;
• open the viewer portal with ?source_ip=… and confirm the balancer response maps to the expected zone and playback_url.

You can validate zones, fallback, and restreamer selection without being on the real subnet or having a “green” edge by metrics. Do not use source_ip in production: it overrides real client IP mapping and is for diagnostics and lab only.

Below are viewer portal examples: the panel shows the final playback_url from the balancer. With source_ip=10.1.0.1 (zone with route 10.1.0.0/16) the URL shows the first office edge (srv1 in the sample lab):

With source_ip=10.2.0.2 the zone 10.2.0.0/16 and matching restreamer (srv2) are selected:

Verifying CDN configuration¶

After setup, walk through:

1. Open streamers and confirm the restreamer exists and is not disabled.
2. Confirm zone and playback_base_url are set.
3. Open the zone card and verify the CIDR is saved correctly.
4. If using fallback, confirm it is correct and skip-liveness is enabled only where you intend for tests.
5. Confirm the stream exists and works on origin.
6. Confirm the restreamer receives external configuration via config_external.
7. Open the viewer portal from a network whose IP maps to the intended zone.
8. Confirm playback goes through the local restreamer, not directly from origin.

Practically, test from a workstation in that branch or a test host in the right segment.

What the user sees when CDN is correct¶

For end users CDN is invisible. They open a normal stream link while Agora:

• picks the appropriate zone;
• chooses the best restreamer;
• directs playback to the local distribution URL.

Users do not manually pick office, node, or broadcast point.

Common misconfiguration issues¶

If CDN misbehaves, check:

• restreamer is restreamer, not a plain origin;
• restreamer is not disabled;
• playback_base_url is set;
• restreamer is bound to the correct zone;
• the zone has the right CIDR;
• the client IP actually matches the intended route;
• fallback zone is not wrong;
• origin streamer is up and serving the stream;
• restreamer receives config_external;
• the zone has at least one available restreamer.

If the client IP matches no route, CDN routing does not apply. Then verify masks, routing, and how traffic actually reaches Agora in your network.

Operational recommendations¶

For stable intranet CDN:

• name zones by physical or org topology;
• do not mix unrelated offices in one zone;
• keep at least one backup service path for critical sites;
• monitor restreamer health regularly;
• track origin and edge availability separately;
• document which IP ranges belong to which office.

That simplifies operations, scaling, and failover when the network or individual nodes fail.