Primary and replica servers ​

Run more than one Quikcast server and let the others copy the first one's streams. The primary is the server your encoders connect to. A replica asks the primary which streams it has and relays each one, so listeners can use whichever server is closest, and you add capacity by starting another replica.

This is Icecast's master and slave idea. To relay one or two known streams, use a relay instead. Use a replica when a server should follow every stream of another, including streams added later, without editing its config.

1. Set up the primary ​

Add a [primary] section to the primary's config. It protects the stream list with a password that only your replicas know:

toml
[primary]
username = "replica"
secret_file = "secrets/replica-password"

Make the password at least 16 characters, like a mount password:

sh
openssl rand -base64 24 > secrets/replica-password

That is the whole change. The primary now answers GET /api/streams on its public address, but only with that password. It shares every publicly playable mount except:

  • mounts protected by signed links, because a replica could not play them
  • mounts that are themselves copies made by a replica, so two servers can never copy each other in a loop

To share only some streams, name them:

toml
[primary]
secret_file = "secrets/replica-password"
share = ["/radio.mp3", "/jazz.mp3"]

2. Set up a replica ​

On the other server, add a [replica] section with the primary's address and the same password:

toml
[replica]
primary = "https://radio.example.com"
username = "replica"
secret_file = "secrets/primary-password"

The replica needs no [[mounts]] of its own. Within a few seconds of starting, every stream on the primary appears at the same path: https://radio.example.com/radio.mp3 is also https://eu.example.com/radio.mp3.

primary is the server's address only, with no path. The replica reads the stream list and relays the audio over that same public address.

How it behaves ​

  • Streams follow the primary. The replica checks the list every refresh_secs (30 by default). A new stream gets a mount and a relay. A stream that leaves the list is removed, and its listeners are disconnected.
  • Relays connect on demand. A replica connects to the primary for a stream only while someone is listening, then disconnects after a while, so 40 streams do not mean 40 open connections. The first listener of a quiet stream waits a moment. See on-demand relays; set on_demand = false to keep every relay connected.
  • A primary that goes down does not take the replica down. If the list cannot be read, the replica keeps the streams it has and logs a warning once. It carries on when the primary returns.
  • Your own mounts win. If the replica already has a [[mounts]] entry with the same path, that mount is left alone and the primary's stream with that path is not copied.
  • They are normal relays. Replicated streams show under Relays and Mounts in the console and in the management API like any other relay.
  • Listeners count on the replica. The primary sees one connection per stream, not one per listener, so its load stays flat as you add replicas.

Send listeners to replicas ​

A primary can redirect listeners to its replicas, as Icecast does, so audio no longer flows through the primary. Turn it on in two places.

On each replica, say what its own public address is. The replica then announces itself, and the streams it carries, to the primary every time it checks the list:

toml
[replica]
primary = "https://radio.example.com"
secret_file = "secrets/primary-password"
public_url = "https://eu.example.com"

On the primary, choose when to redirect:

toml
[primary]
secret_file = "secrets/replica-password"
redirect_after = 200

With redirect_after = 200, the first 200 listeners of each mount connect to the primary. Everyone after that gets an HTTP 302 to a replica that carries the mount, taking turns between replicas. redirect_after = 0 sends every listener to the replicas, which is the way to keep the primary for encoders and replicas only. A listener the primary has no room for (a full listener_limit or the global limit) is redirected too, whatever the number.

What to know:

  • Nothing changes until a replica announces itself. If no replica is available for a mount, listeners are served by the primary as before.
  • Replicas drop out when they go quiet. A replica that misses two checks in a row stops receiving listeners, so a replica that is down is not handed out.
  • Replicas are never redirected. Their own audio requests are marked, so a replica always gets its stream from the primary.
  • Players must follow redirects. Browsers, VLC, FFmpeg and most apps do. A few very old players do not, so test the ones your listeners use. Keep redirect_after above zero if you are unsure.
  • Signed-link mounts are never redirected, because replicas do not carry them.
  • public_url is just an address, like primary: no path. It must be reachable by your listeners, not only by the primary.
  • Metrics. listeners_redirected_total counts every redirect.

Limits and sizing ​

SettingDefaultMeaning
refresh_secs30How often the stream list is checked (5 to 3600).
on_demandtrueConnect to the primary only while someone listens.
max_streams16The most streams to copy (1 to 48).
onlyallCopy only these paths, for example ["/radio.mp3"].

Every copied stream is one mount and one relay on the replica, so the usual limits apply: at most limits.max_mounts (64 by default) mounts and 64 relays in total, and limits.relay_allocation_budget must have room for the relays (2 MiB each, 32 MiB by default, which is enough for 16). If the primary has more streams than fit, the replica copies the first ones in alphabetical order and logs a warning. Raise max_streams and the budget together if you need more.

Security ​

  • The stream list needs the replica password. Without it the primary answers 401. The password is a separate secret from encoder, management and console passwords.
  • Use HTTPS between the servers. A replica verifies the primary's certificate, and the password is only sent to the primary's own address.
  • Streams are relayed over the primary's public listener, so the primary's access rules apply to the replica like any other listener. If you restrict listeners by IP or country, allow your replicas' addresses.

Check that it works ​

On the replica, list the discovered streams:

sh
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:9090/api/relays

Replicated streams appear as relays whose origin is the primary. If nothing appears, look at the replica's log:

Log lineMeaning
the primary rejected the replica username or passwordThe username or password does not match the primary's [primary] section.
the primary has no [primary] sectionThe primary answered 404. Add [primary] there and reload it.
could not reach the primaryThe address, port or TLS is wrong, or a firewall is in the way.

A replica needs its config file

A replica applies stream changes by reloading its configuration file, so it must be started with --config (or QUIKCAST_CONFIG), as in every normal setup.