Icecast Streaming Media Server on AWS User Guide

Overview

This AMI runs Icecast 2.4.4, the open source streaming media server from the Xiph.Org Foundation. Icecast is the server behind a great many internet radio stations. A source client such as butt, Mixxx, liquidsoap, ices or OBS pushes a live audio stream to a mountpoint on the server, and Icecast relays that single stream out to many simultaneous listeners over ordinary HTTP. It speaks Ogg Vorbis, Opus and MP3, publishes M3U and XSPF playlists that any media player understands, and exposes a public status page plus a password protected admin interface for managing mountpoints and listeners.

Because Icecast relays over plain HTTP, listeners need no special software: a browser, VLC, or any internet radio app can play a mountpoint directly.

Secure by default. The stock Icecast configuration ships with the well known default password hackme for its source, relay and admin accounts. This image ships no working password at all. On the first boot of every instance, icecast-firstboot.service generates three independent random passwords, writes them into the configuration, and records them in a root only file. Icecast is configured to refuse to start if that rotation has not run, so an instance can never come up serving a default or placeholder credential.

What is included:

• Icecast 2.4.4, installed from the stock Ubuntu 24.04 archive package so it inherits Ubuntu's security maintenance
• Icecast listening on port 8000, its native port, for both listeners and source clients
• nginx on port 80 reverse proxying the status and admin interface, so the server is reachable without a port suffix, plus an unauthenticated /healthz endpoint for load balancer health probes
• Per instance admin, source and relay passwords generated on first boot and recorded at /root/icecast-credentials.txt (mode 0600)
• icecast2.service, nginx.service and a one shot icecast-firstboot.service as systemd units, enabled and active
• A fully patched Ubuntu 24.04 LTS base with unattended security upgrades enabled
• 24/7 cloudimg support

Prerequisites

An active AWS account, an EC2 key pair in the target region, and a VPC with a public subnet. An m5.large (2 vCPU / 8 GiB RAM) comfortably serves a typical station; Icecast is light on CPU because it relays the source stream rather than re encoding it, so listener count is mostly a bandwidth question. Security group inbound: allow 22/tcp from your management network, 80/tcp for the status and admin interface, and 8000/tcp for listeners and source clients.

Icecast serves plain HTTP. For a public station, or any time an admin or source password crosses the internet, terminate TLS in front of it with your own domain using a reverse proxy or an Application Load Balancer.

Step 1 - Launch from the AWS Marketplace

Sign in to the AWS Marketplace, search for Icecast by cloudimg, and choose Continue to Subscribe then Continue to Configuration. Pick your region and the AMI fulfilment option, then Continue to Launch. Under Launch this software choose Launch through EC2, select your instance type, key pair and subnet, and a security group that opens ports 22, 80 and 8000. Launch the instance.

Step 2 - Launch from the EC2 CLI

# Create a security group that opens SSH, the web interface and the native Icecast port
aws ec2 create-security-group --group-name icecast-sg \
  --description "Icecast" --vpc-id <your-vpc-id>

aws ec2 authorize-security-group-ingress --group-name icecast-sg \
  --ip-permissions \
    IpProtocol=tcp,FromPort=22,ToPort=22,IpRanges='[{CidrIp=<your-admin-cidr>}]' \
    IpProtocol=tcp,FromPort=80,ToPort=80,IpRanges='[{CidrIp=0.0.0.0/0}]' \
    IpProtocol=tcp,FromPort=8000,ToPort=8000,IpRanges='[{CidrIp=0.0.0.0/0}]'

aws ec2 run-instances \
  --image-id <icecast-ami-id> \
  --instance-type m5.large \
  --key-name <your-key-pair> \
  --security-groups icecast-sg \
  --subnet-id <your-public-subnet> \
  --associate-public-ip-address

Step 3 - Connect to your instance

Connect over SSH as the default login user for your AMI variant:

ssh -i <your-key.pem> ubuntu@<instance-public-ip>

Step 4 - Confirm the services are running

Three units make up the appliance: icecast-firstboot.service runs once on first boot to generate this instance's passwords, icecast2.service is the streaming server itself, and nginx.service fronts it on port 80. Confirm all three are active, and that Icecast is listening on port 8000 with nginx on port 80:

systemctl is-active icecast2 nginx icecast-firstboot
sudo ss -tlnp | grep -E ':80 |:8000 '

Expected output:

active
active
active
LISTEN 0      5            0.0.0.0:8000      0.0.0.0:*    users:(("icecast2",pid=...))
LISTEN 0      511          0.0.0.0:80        0.0.0.0:*    users:(("nginx",pid=...))
LISTEN 0      511             [::]:80           [::]:*    users:(("nginx",pid=...))

Step 5 - Retrieve your per instance passwords

On first boot, icecast-firstboot.service generated three independent random passwords for this instance and recorded them in a root only file:

• ICECAST_ADMIN_PASSWORD signs you in to the admin interface as user admin
• ICECAST_SOURCE_PASSWORD is what a source client uses (with user source) to start broadcasting
• ICECAST_RELAY_PASSWORD is used by another Icecast server pulling a relay from this one

Read them with:

sudo cat /root/icecast-credentials.txt

The three passwords are distinct on purpose: handing a presenter the source password does not give them admin access. When you need to share the file, for example in a support bundle or a screenshot, print it with the secrets masked:

sudo sed -E 's/^(ICECAST_[A-Z_]*PASSWORD=).*/\1********/' /root/icecast-credentials.txt

Step 6 - Confirm the server is serving

nginx serves an unauthenticated /healthz endpoint for load balancer probes, and Icecast publishes machine readable server statistics at /status-json.xsl. The admin interface requires the password from Step 5, so an unauthenticated request is rejected with 401 while an authenticated one returns 200:

curl -sI http://127.0.0.1/healthz | head -1
curl -s http://127.0.0.1/status-json.xsl | jq -r '.icestats.server_id'

PW=$(sudo grep '^ICECAST_ADMIN_PASSWORD=' /root/icecast-credentials.txt | cut -d= -f2-)
curl -s -o /dev/null -w "no auth  -> HTTP %{http_code}\n" http://127.0.0.1/admin/stats
curl -s -o /dev/null -w "with pw  -> HTTP %{http_code}\n" -u "admin:$PW" http://127.0.0.1/admin/stats

Expected output:

HTTP/1.1 200 OK
Icecast 2.4.4
no auth  -> HTTP 401
with pw  -> HTTP 200

Step 7 - Confirm no default password shipped

Upstream Icecast ships the default password hackme. This image removes it everywhere, including from the commented examples in the configuration file, and generates per instance secrets instead. Prove it for yourself: the default appears nowhere in the configuration, it does not authenticate, and icecast2.service declares a hard Requires dependency on the first boot rotation so it cannot start without real per instance credentials:

sudo grep -c hackme /etc/icecast2/icecast.xml || echo "0 (the upstream default password is not present)"
curl -s -o /dev/null -w "admin:hackme -> HTTP %{http_code}\n" -u admin:hackme http://127.0.0.1/admin/stats
systemctl show icecast2 -p Requires --value

Expected output:

0 (the upstream default password is not present)
admin:hackme -> HTTP 401
icecast-firstboot.service system.slice sysinit.target -.mount

Step 8 - Set your public hostname

Icecast uses the <hostname> setting to build the stream URLs it advertises: the listen URLs on the status page, and the contents of the M3U and XSPF playlists listeners download. On first boot the appliance resolves this automatically from the EC2 instance metadata service (IMDSv2), but an instance launched without a public IP will have fallen back to its private address. Check what it resolved to:

grep -E '<hostname>' /etc/icecast2/icecast.xml

If that is a private address (for example 10.x.x.x) then playlists handed to external listeners will not work. It is good practice in any case to publish a stable DNS name rather than an IP, because an EC2 public IP can change on stop/start. Set it to the name or address your listeners will use, then restart Icecast:

sudo sed -i -E 's#<hostname>[^<]*</hostname>#<hostname>radio.your-domain.example</hostname>#' /etc/icecast2/icecast.xml
sudo systemctl restart icecast2

Step 9 - Open the status page

Browse to http://<instance-public-ip>/. The public status page lists every active mountpoint with its stream name, description, content type, listener count and current track, together with M3U and XSPF playlist links and an inline player. With no source client connected the page simply reports that there are no mountpoints; the screenshot below shows the page with a live Ogg Vorbis stream connected.

Step 10 - Connect a source client

A source client runs on your machine, not on the instance, and pushes audio to a mountpoint. Point any Icecast compatible client at the server using the source password from Step 5:

Server / host : <instance-public-ip>   (or your DNS name from Step 8)
Port          : 8000
Mountpoint    : /stream.ogg
Username      : source
Password      : the ICECAST_SOURCE_PASSWORD value from Step 5
Format        : Ogg Vorbis, Opus or MP3

Popular choices are butt (Broadcast Using This Tool) and Mixxx for live shows, liquidsoap for scripted or automated stations, and OBS Studio for streaming a desktop or console audio feed. Once connected, the mountpoint appears immediately on the status page from Step 9 and listeners can tune in at http://<instance-public-ip>:8000/stream.ogg.

Step 11 - Manage mountpoints in the admin interface

Browse to http://<instance-public-ip>/admin/ and sign in as admin with the password from Step 5. Admin Home shows global server statistics: the resolved host, total connections, current listeners, source count and server version.

Mountpoint List shows every active mountpoint with its live controls: List Clients to see who is connected, Move Listeners to migrate an audience to another mountpoint without interrupting them, Update Metadata to change the track title shown to listeners, and Kill Source to disconnect the broadcaster.

Step 12 - Inspect connected listeners

From the Mountpoint List choose List Clients on any mountpoint to see each connected listener: their IP address, how long they have been connected and the player they are using. Each row has a Kick action to disconnect a single listener.

Maintenance

• Configuration: everything lives in /etc/icecast2/icecast.xml. Restart with sudo systemctl restart icecast2 after editing. Common changes are raising <clients> in <limits> for a larger audience, and adding <mount> sections to set per mountpoint limits or fallback streams.
• Logs: access and error logs are in /var/log/icecast2/. They are rotated by the packaged logrotate configuration.
• Rotating passwords: edit the <source-password>, <relay-password> and <admin-password> values in /etc/icecast2/icecast.xml and restart Icecast. The first boot generator only runs once, on first boot, so it will not overwrite your changes.
• Backups: Icecast keeps no database and stores no recordings by default; it relays live audio. The configuration file is the only state worth backing up.
• Security updates: unattended security upgrades are enabled, so the OS keeps itself patched. Reboot when a new kernel is installed.
• TLS and access control: for a public station, front Icecast with your own domain and a TLS terminating reverse proxy or an Application Load Balancer, and restrict the admin interface in the security group to the networks that need it.

Support

cloudimg provides 24/7/365 expert technical support for this image. Contact support@cloudimg.co.uk. Icecast is developed by the Xiph.Org Foundation and licensed under the GNU General Public License version 2; the corresponding source is available from the Ubuntu archive with apt-get source icecast2. This image is provided by cloudimg and is not affiliated with or endorsed by the Xiph.Org Foundation; additional charges apply for build, maintenance and 24/7 support.