The Icecast2 server
Overwiew

Icecast2 is a software very easy to install and mantain. Currently, versions for major Operating Sistems are available from the Icecast2 home page. Icecast2 is an open source project mantained by the Xiph community, home of the ogg/Vorbis software family.

Introduction

Icecast2 is a streaming media server which currently supports Ogg Vorbis and MP3 audio streams. It can be used to create an Internet radio station or a privately running jukebox and many things in between. It is very versatile: new formats can be added relatively easily and supports open standards for commuincation and interaction.

There are two major parts to most streaming media servers: the component providing the content (what we call broadcaster) and the component which is responsible for serving that content to listeners (this is the function of icecast2). This means that there are at least two programs running: the streaming server (icecast2 in this case) and the broadcaster. The icecast2 server will be the place where all listeners of your station will connect. The broadcaster usually runs on a separate machine than icecast2, but it does not necessarily need to. Broadcasters send the content to icecast2 and provide the stream data (encoded audio) that is then relayed out to listeners by icecast2. It is important to note that not every streaming software works with icecast2. You will need to check that icecast2 is supported by the software that you are going to use for broadcasting.

Each icecast2 server can house multiple broadcasts (or mountpoints) each containing a separate stream of content. A listener can only listen to a single mountpoint at a time. This means you can have a single icecast2 server containing either multiple broadcasts with different content, or possibly the same broadcast but with streams of different bitrates or qualities. In this case each broadcast or stream is a separate mountpoint.


Install Icecast2

Microsoft OS

Download the "Windows setup icecast2 win32" file from the Icecast2 home page. This is an autoinstaller, that means you will be guided through the install process, and, once installed, in "Start" > "Programs" you will be able to find the Icecast2 control window.


Macintosh OS

First you'll have to install "Darwin ports" on your computer. This is a two-step process and is easy to get working. The first step is to download and run the Darwin Ports installer from darwinports.opendarwin.org; you will need the latest ".dmg" version of the software. Second step is to update the ports on your Mac: open a terminal window, check the project out of the CVS repository with the following command and enter the root password when prompted:

% sudo port -d selfupdate

Password:

Once Darwin Ports has been installed, in a terminal window and while online, type the following and hit return:

% sudo port install icecast2

Password:

You will be prompted for your root password, which you should enter. You may have to wait for a few minutes while the software is retrieved from the network and installed for you. Finally, on the prompt command will appear something that looks similar to:

---> Fetching icecast2

---> Verifying checksum for icecast2

---> Extracting icecast2

---> Configuring icecast2

---> Building icecast2 with target all

 

---> Staging icecast2 into destroot

 

---> Installing icecast2

Make sure that you do not close the terminal window while Darwin Ports is working. Once the software has been installed, you can find further information about using icecast2 with these commands:

% man icecast2

% apropos icecast2

% which icecast2

% locate icecast2


GNU/Linux

Icecast2 is present in all the major GNU/Linux distributions. If you want to self compile the software, you can download the source code from the Icecast2 home page.

If you are a Debian (Ubuntu, Knoppix, ...) user, you can simply open a terminal, as root or with sudo, and write:

root@host:~$ apt-get update

root@host:~$ apt-get install icecast2

Similary, with a Gentoo distribution you can directly download the "emerge" packet, or the ".rpm" packet for a Red Hat distribution.

The config file is then located in the /etc/icecast2/ directory.

After editing and saving icecast2.xml, you can start the icecast2 server opening a root shell and typing:

/etc/init.d/icecast2 start

Icecast2 can also be launched directly from the command line, using the syntax icecast2 -c path/to/config/file. However, we recommend starting icecast2 from the init script.

When you start icecast2 from the init script, the script will read the defaults specified in /etc/default/icecast2 and behave accordingly. In particular, you won't be able to start the server this way unless the variable ENABLE (the last one in /etc/default/icecast2) is set to true.

For security reasons, the User ID and group ID of the running server will be changed to icecast2 and icecast2, respectively. The log directory specified by the <logdir> directive of the configuration file should be writable by the user icecast2, otherwise the server won't start properly.


Basic configuration

Configuration of the icecast2 server is done by editing the file icecast2.xml. This file, unlike many configuration files you might have seen before, is in XML format.

For a basic setup, the following elements in icecast2.xml need to be properly configured:

  • <source-password> - Every source client will need to supply this password to be able to stream to the server.

  • <admin-password> - will be used to access admin features of icecast2.

  • <listen-socket> - This is the port and IP address that the server will be listening on.

  • <logdir> - The directory where log files will be placed.

  • <webroot> - The directory where any static content should be placed (file serving root).

  • <adminroot> - The directory containing the xslt files.

Checking the icecast2 server start

Once the icecast2 server is started, it will wait for a source client to provide data for streaming. When at least one stream is set up, icecast2 will wait for listening clients to connect to the stream and download it.

You can check if icecast2 has been started succesfully by launching a web browser and opening the following URL: http://yourip:port/admin/stats.xml. You have to substitute yourip by your machine's IP address, and port by the port icecast2 is listening on (by default it is 8000), as specified in the <listen-socket> element in the server configuration file.

On the computer where the Icecast2 server is running, you can check if icecast2 has started succesfully by browsing the URL: http://localhost:8000/admin/stats.xml

When you try to open the icecast2 administration interface, you will be prompted for the administrator username and password. In a standard GNU/Linux distribution, both of them are admin.

Parameters for the broadcaster configuration

Once you have succesfully started the icecast2 server, it's time to do some configuration on your source client - i.e. the program which will encode audio data and send it to the server. There are many different source clients available on the Internet.

However, before going on to the broadcaster configuration, take one minute to write down the following information, taken from the server configuration file: these are the informations that the broadcaster needs to know in order to be able to stream to your Icecast2 server!

  • IP address and Port of the icecast2 server - both of these come from <listen-socket>

  • source password - from <source-password>.

Choosing a mountpoint name

Each icecast2 server can house multiple broadcasts (or mountpoints) each containing a separate stream of content. A listener can only listen to a single mountpoint at a time. This means you can have a single icecast2 server contain either multiple broadcasts with different content, or possibly the same broadcast but with streams of different bitrates or qualities. In this case each broadcast or stream is a separate mountpoint. Whenever a listener wishes to connect to a stream, she needs to know both the server address and port and the name of the mountpoint she wants to connect to.

During the source client configuration, you have to choose a mountpoint name for every stream you want to set up. During the streaming server configuration, you can change the specific server-side settings for each mountpoint. For now, you can start thinking of a mountpoint name for every stream that you will host on your icecast2 server. When choosing a name for a mountpoint, keep in mind that mountpoints names associated to OGG streams should end in .ogg (e.g. mystream.ogg). They should not contain spaces or punctuation characters (except from .).



Finetuning the configuration file

The icecast2 configuration file is normally called icecast2.xml, and, in a GNU/Linux distribution, it is located under the /etc/icecast2/ directory. You can either edit this file or create a custom configuration file, and place it anywhere you like. If you wish to start icecast2 using a custom configuration file, you should also edit the file /etc/default/icecast2, and specify the new configuration file path under CONFIGFILE.

The icecast2.xml file is in XML syntax. It consists of elements grouped into sections. Each section begins with a tag named after the section name (e.g. <limits>) and is closed by a corresponding end tag (e.g. </limits>). The following links will take you to the part of the icecast2 manual appropiate for each section.

  • Limits

    This section contains server level settings that, in general, do not need to be changed. Only modify this section if you are know what you are doing.

  • Authentication

    This section contains all the users and passwords used for administration purposes or to connect sources and relays.

  • Yp Directory Settings

    This section contains all the settings for listing a stream on any of the Icecast2 YP Directory servers. Multiple occurances of this section can be specified in order to be listed on multiple directory servers.

  • Misc Server settings

    This section contains miscellaneous server settings. Note that multiple listen-socket sections may be configured in order to have icecast2 listen on multiple network interfaces. If a bind-address is not specified for a particular listen-socket, then the hostname parameter will be used to specify the address that will be bound.

  • Relay settings

    This section contains the server's relay settings. There are two types of relays: a "Master server relay" or a "Specific Mountpoint relay." A Master server relay is only supported between icecast2 servers and is used to relays all mountpoints on a remote icecast2 server.

  • Mount Specific settings

    This section contains settings which apply only to a specific mountpoint. Within this section you can reserve a specific mountpoint and set a source username/password for that mountpoint (not yet implemented) as well as specify individual settings which will apply only to the supplied mountpoint.

  • File path settings

    This section contains paths which are used for various things within icecast. All paths should not end in a '/'.

  • Logging

    This section contains information relating to logging within icecast. There are two logfiles currently generated by icecast, an error.log (where all log messages are placed) and an access.log (where all stream/admin/http requests are logged).

    Note that on non-win32 platforms, a HUP signal can be sent to icecast in which the log files are re-opened for appending giving the ability move/remove the log files.

  • Security

    This section contains configuration settings that can be used to secure the icecast server by performing a chroot to a secured location. This is currently not supported on win32.