Icecast relay server: scaling a station past one machine

Where one Icecast server runs out

A single Icecast box has three ceilings. The first is configured: clients in the limits block caps concurrent connections server-wide rather than per mount, and the docs count stats requests and static files in it as well as listeners. The second is the port. The third is geography: every listener, wherever they are, opens a connection to that one city.

The table is our own multiplication of bitrate by listeners, audio payload only. TCP and HTTP overhead come on top, so treat each figure as a floor, not a sizing guarantee.

Relays move the second and third ceilings. The master sends one copy per relay, and each relay carries its own listeners on its own port, in its own city.

How Icecast relaying works

Relaying is pull-based. The configuration reference says the receiving server connects to the sending server as if it were a listener, so the master needs no relay section of its own. For a specific-mountpoint relay the relaying guide notes the master need not be configured at all and is unaware it is being mirrored; a master-server relay instead logs in with the master's relay-user and relay-password when it fetches the mount list. The master does not have to run Icecast either for a per-mount relay: SHOUTcast and Icecast 1.x masters are supported.

Master-server relay configuration

These elements go in the relay's icecast.xml. On start it logs in to the master with master-username and master-password, fetches the list of mounts and starts pulling them; every master-update-interval it asks again for mounts that have appeared since.

<!-- on the relay (slave) -->
<master-server>master.example.net</master-server>
<master-server-port>8000</master-server-port>
<master-update-interval>120</master-update-interval>
<master-username>relay</master-username>
<master-password>REPLACE_WITH_RELAY_PASSWORD</master-password>
<relays-on-demand>1</relays-on-demand>

The username and password must match relay-user and relay-password in the master's authentication block; the username defaults to relay. A mount set to hidden on the master is not copied. With relays-on-demand set to 1, a relay only pulls a stream while it has at least one listener for it, which the relaying guide frames as avoiding bandwidth costs when nobody is tuned in.

Relaying a single mount

Use a relay block when you want one mount, a different local name, or a master that is not Icecast 2.

<relay>
    <server>master.example.net</server>
    <port>8000</port>
    <mount>/live.mp3</mount>
    <local-mount>/live-eu.mp3</local-mount>
    <relay-shoutcast-metadata>1</relay-shoutcast-metadata>
    <on-demand>0</on-demand>
</relay>

username and password are only needed when the remote mount asks for them. When the master is a SHOUTcast server, mount must be /; relay-shoutcast-metadata (on by default; 1 in the example) carries song titles, if the remote server sends them; SHOUTcast embeds them in the stream itself. on-demand defaults to whatever relays-on-demand says; 0 keeps the relay connected around the clock.

Limits to raise on every relay

• clients: listeners plus every stats and file request, server-wide. Size it to the audience this box should take.
• sources: the docs count active relays as well as source clients. The example in the reference uses 2, so a box relaying four mounts needs at least 4.
• queue-size: the buffer that holds a lagging listener; a listener whose queue grows past it is dropped. The reference gives 512k as the default.
• burst-size: data sent at connect time to fill the player's pre-buffer, 64 KB by default. Keep it smaller than queue-size, or new listeners can be cut off by their own burst.
• Fallback files on the master: the docs warn that fallback files play untimed, so on a master mount the relay reads one too fast and its listeners are eventually kicked. Put fallback files on relay mounts instead.

Keeping the relay password secret

The relay credentials are what lets a relay ask the master for its mount list, so treat them like the source password. The reference calls source-password unencrypted, and relay-password, admin-password and the relay's master-password sit beside it in icecast.xml as plain text.

1. Give the relay its own long random password, different from the source and admin passwords.
2. Our advice: make icecast.xml readable by root and Icecast's group only. Set the owner with chown root:icecast icecast.xml, using the group your Icecast runs as, then chmod 640 icecast.xml. Do this on the master and on every relay.
3. Keep the file out of any public repository and out of backups other people can read.
4. Our advice: if your main server only feeds relays, let its port accept connections only from the relays' addresses, your encoder's address and wherever you reach the admin pages from. Leave the encoder out and the station goes off air.

The managed route: the radio CDN

Our radio CDN does the relay job for a hosted station. The station stays hosted on a single server, in either New York or Bucharest; on the Platinum plan, each listener opens one CDN link and is served by the nearest of five cities: New York, Miami, San Francisco, Amsterdam and Bucharest. Each nearby server fetches one copy of the stream from the station's server and hands it to everyone listening there.

• Steering: a nameserver of ours answers with the healthy servers nearest the listener's network, cached for 60 seconds.
• Encoders: ingest.radio.serverroom.net on port 14000 (14001 for SHOUTcast v1) takes the encoder in at the nearest city and passes it, unchanged, to the station's server, which still checks the password.
• Failures: every server is checked every 10 seconds; after 2 failed checks in a row it is left out of the answers, and within about a minute and a half new connections go to another server in the same city or to the next city on the list. A failure of the server hosting the station takes it off the air in every city.
• Figures: each listener counts once in the station's statistics, whichever server they came through.

Every station runs its own Icecast 2.5 process; the Icecast hosting page has the mounts and encoder settings. The Platinum ceiling is 5,000 concurrent listeners; a larger audience is quoted.

When your own relays are the right call

Run relays yourself when you need control the managed plan does not give: your own Icecast build and config, cities of your choosing, or mounts and authentication rules of your own. That means a master plus one machine per relay location, each a dedicated streaming server on an unmetered port where nothing counts the traffic. The port is 1 Gbps on 10 of our 18 configurable lines and 500 Mbps on the other 8, so check the line against the table above.

If the station is not on air yet, start with the whole chain from microphone to listener in starting an online radio station; relays are a problem for later.