Icecast Streaming Howto for Gentoo

[darfsnuzal]

Icecast Streaming Howto for Gentoo

1. Introduction

I really didn't understand how icecast worked when I first decided that I wanted a streaming audio server. After pulling a bunch of information of off the net I learned that there are about 3,000 different ways to stream audio and half of the howto's telling you what to do are either out of date or just plain wrong. I finally figured out how to get a server set up and decided to document the steps I took. This howto should provide you with the steps required to set up icecast (the streaming server that clients connect to) and ices (the application that streams audio to icecast). Please feel free to provide comments and corrections and I'll update this document accordingly.

Your streaming audio server will stream audio to both a local LAN or the Internet. With this fact in mind, this howto will attempt to guide the user to the most secure installation of icecast and ices reasonably possible. If you decide to undo the security built into this howto and run icecast or ices as root, please consider the consequences should someone compromise your icecast server.

Important: This howto was written for icecast-2 and ices-2. Previous versions of icecast and ices streamed audio using the MP3 format. As of version 2 ices now only supports the OGG format while icecast-2 still retains the ability to stream MP3. This may impact which clients can listen to your stream. If you require a MP3 stream you might want to look at Muse. I have included instructions for connecting Muse to icecast at the end of this howto. For a nifty MP3 to OGG converter, check out Oggasm.

2. Installing icecast and ices
USE Flags

Icecast can use the curl USE flag but this howto will not use it.

Installation

Both icecast and ices are currently in the Portage tree and should be straight forward to set up.

Code Listing 2.1: Emerging necessary packages

Code: Select all

# emerge -v icecast ices

Configuring icecast

Because icecast listens for client connections over a network we want to be very careful. If we run icecast as root and someone finds a flaw in it that allows an attacker to gain shell access, they will have a root shell to the system. To help avoid this situation we will run both icecast and ices as an unprivileged user: icecast. If someone compromises icecast and gains a shell to the system they will not automatically gain superuser access.

Code Listing 2.2: Creating the icecast user

Code: Select all

# groupadd icecast
# useradd icecast -m -g icecast -G users,wheel,audio -s /bin/bash
# passwd icecast

Now we will change to the icecast user and complete the configuration of icecast.

Code Listing 2.3: Configuring icecast

Code: Select all

# su - icecast
$ mkdir log
$ cp /etc/icecast2/icecast.xml .

Edit the icecast.xml file and change the following options:

Code Listing 2.4: Changes to icecast.xml

Code: Select all

<source-password>$passwd</source-password>
<relay-password>$passwd</relay-password>
<admin-password>$passwd</admin-password>
<hostname>$hostname</hostname>
<logdir>/home/icecast/log</logdir>

        <!--                            # Remove
        <changeowner>
            <user>icecast</user>        # Change to icecast
            <group>icecast</group>      # Change to icecast
        </changeowner>
        -->                             # Remove

Replace $passwd with the password you want to secure icecast with. $hostname should match the name of your machine. Exit the shell and start icecast to verify that the configuration is valid:

Code Listing 2.5: Starting icecast

Code: Select all

$ exit
# icecast -b -c /home/icecast/icecast.xml

Check the file /home/icecast/log/error.log. You should see something similar to this:

Code Listing 2.6: Verifying icecast startup

Code: Select all

[2004-07-19  01:06:32] INFO main/main icecast server started

Configuring ices

At this point, we've got icecast up and running. Icecast is now ready to receive the music stream from ices. Let's configure ices:

Code Listing 2.7: Configuring ices

Code: Select all

# su - icecast
$ cp /etc/ices2/ices-playlist.xml.dist ./ices-playlist.xml

Edit the ices-playlist.xml and change the following settings:

Code Listing 2.8: Changes to ices-playlist.xml

Code: Select all

<background>1</background>
<logpath>/home/icecast/log</logpath>
<hostname>$hostname</hostname>
<password>$passwd</password>
<param name="file">/home/icecast/playlist.txt</param>
<mount>/$stream_name.ogg</mount>                            # Must include .ogg

Note: Your stream name needs to end with ".ogg" or most media players will not recognize your icecast stream as an OGG stream.

Starting ices

Now that we have ices and icecast configured you will need to create a playlist for ices to stream to icecast. In this howto we've chosen /home/icecast/playlist.txt file to hold our playlist. The playlist is a text file with one absolute path per OGG file per line. We can create a playlist from an existing directory of OGG files:

Code Listing 2.9: Quick creation of a playlist

Code: Select all

$ find $ogg_dir -name *.ogg -print > playlist.txt

Ices will stream each song in the order it is listed in the playlist unless you set the <random> parameter to "1" in the ices-playlist.xml. If the <restart-after-reread> parameter is set to "1", ices will restart the playlist at the first file listed if the playlist is updated while ices is running.

Now let's start ices as the icecast user:

Code Listing 2.10: Starting ices

Code: Select all

$ ices ./ices-playlist.xml

If no error messages are displayed, you should be able to verify the ices to icecast connection by using your browser to view http://$hostname:8000/admin/stats.xsl. You should see the mount point /$stream_name.ogg in the list of mount points. If your stream appears you should be able to connect to the stream by using the URL http://$hostname:8000/$stream_name.ogg.m3u.

If you hear your stream, congratulations! You now have a streaming audio server. After you're done strutting your stuff to your new music stream, close down ices and icecast and proceed to the next section where we will create startup and shutdown scripts for ices and icecast.

Code Listing 2.11: Hard shutdown of ices and icecast

Code: Select all

$ exit
# killall ices
# killall icecast

3. Icecast and ices startup/shutdown

When you emerge ices and icecast Portage does not create startup or shutdown scripts for you. You can use the following scripts to start and stop ices and icecast:

Code Listing 3.1: /etc/init.d/ices

Code: Select all

#!/sbin/runscript
# Copyright 1999-2004 Gentoo Technologies, Inc.
# Distributed under the terms of the GNU General Public License v2

depend() {
        need icecast net
        use dns
}

start() {
        ebegin "Starting ices"
        start-stop-daemon --start --chuid icecast --quiet --exec /usr/bin/ices \
                -- /home/icecast/ices-playlist.xml >/dev/null 2>&1
        eend $?
}

stop () {
        ebegin "Stopping ices"
        start-stop-daemon --stop --retry 5 --quiet --exec /usr/bin/ices
        eend $?
}

Code Listing 3.2: /etc/init.d/icecast

Code: Select all

#!/sbin/runscript
# Copyright 1999-2004 Gentoo Technologies, Inc.
# Distributed under the terms of the GNU General Public License v2

depend() {
        need net
        use dns
}

start() {
        ebegin "Starting icecast"
        start-stop-daemon --start --quiet --exec /usr/bin/icecast \
                --background -- -b -c /home/icecast/icecast.xml >/dev/null 2>&1
        eend $?
}

stop () {
        ebegin "Stopping icecast"
        start-stop-daemon --stop --retry 5 --quiet --exec /usr/bin/icecast
        eend $?
}

If you want ices and icecast to start on system boot, use rc-update:

Code Listing 3.3: Starting icecast and ices at boot

Code: Select all

# rc-update add ices default

Note: the ices startup script will automatically start icecast if it is not already started.

4. Installing and configuring muse
So the OGG format just won't work for you? Well there is a way to stream MP3 formatted streams using muse and this section will demonstrate how to hook up muse to icecast. I strongly recommend that you follow the previous sections and get icecast and ices working even if you do not want to stream music using the OGG format.

Note: Muse is limited in its abilities to play user created playlists. As far as I can tell there is no way to randomize a playlist at the time it is being streamed. This means that muse will play songs in the order they are listed in your playlist. Also, muse does not send information regarding the current song to icecast.

Important: Muse is a gruff little bear to deal with. It doesn't like being detached from a TTY and has no built-in ability to migrate itself to the background. It also does not have an option to write its logs to a file; it wants to write to standard error. This means that while this howto is designed with logging in mind, it just doesn't work so you will not get logs from muse when started with this howto's startup script. Feedback and suggestions are welcome.

USE Flags

Muse can use the following USE flags: debug gtk ncurses. This howto does not use any of these flags.

Installation
Muse is in Portage and installation should be straight forward to install:

Code Listing 4.1: Installing muse

Code: Select all

# emerge -v muse

Now that we've installed muse, we need to create a playlist for it like we do for ices. Muse is picky, however, about the extension of the playlist file so we will use '.pls' as an extension. The file format consists of one path to an MP3 file per line. Let's create a playlist for muse:

Code Listing 4.2: Quick creation of a playlist for muse

Code: Select all

# su - icecast
$ find $mp3_dir -name *.mp3 -print > playlist.pls

Portage will not create startup and shutdown scripts for muse because muse was built to run from console. We can create effective startup and shutdown scripts for muse:

Code Listing 4.3: /etc/init.d/muse

Code: Select all

#!/sbin/runscript
# Copyright 1999-2004 Gentoo Technologies, Inc.
# Distributed under the terms of the GNU General Public License v2

depend() {
        need icecast net
        use dns
}

start() {
        ebegin "Starting muse"
        if [ -n "${MUSE_LOG}" -a ! -f "${MUSE_LOG}" ]; then
                touch "${MUSE_LOG}"
                chown icecast:icecast "${MUSE_LOG}"
        fi
        MUSE_OPTS="-C $MUSE_PLAYLIST -o -e mp3 -b ${MUSE_BITRATE} -q ${MUSE_QUALITY} -r ${MUSE_RATE} -c 2 -s ${MUSE_ICECAST_SERVER} -m ${MUSE_MOUNT} -p ${MUSE_ICECAST_PASSWD} -g cli"
        start-stop-daemon --start --background --chuid icecast --quiet --exec /usr/bin/muse \
                -- ${MUSE_OPTS} >"${MUSE_LOG}" 2>&1
        eend $?
}

stop () {
        ebegin "Stopping muse"
        start-stop-daemon --stop --retry 5 --quiet --exec /usr/bin/muse
        eend $?
}

We also need to create a file to contain muse's command line parameters:

Code Listing 4.4: /etc/conf.d/muse

Code: Select all

# Config file for muse
MUSE_BITRATE="128"
MUSE_QUALITY="9"
MUSE_RATE="44100"
MUSE_MOUNT="$stream_name.mp3"
MUSE_ICECAST_SERVER="localhost:8000"
MUSE_ICECAST_PASSWD="$passwd"
MUSE_PLAYLIST="/home/icecast/playlist.pls"
MUSE_LOG="/home/icecast/log/muse.log"

Replace $stream_name and $passwd with your MP3 stream's name and your icecast password.

If you want muse and icecast to start on system boot, use rc-update:

Code Listing 4.5: Starting icecast and ices at boot

Code: Select all

# rc-update add muse default

Note: The muse startup script will automatically start icecast if it is not already started.

You should be able to verify the muse to icecast connection by using your browser to view http://$hostname:8000/admin/stats.xsl. You should see the mount point /$stream_name.mp3 in the list of mount points. If your stream appears you should be able to connect to the stream by using the URL http://$hostname:8000/$stream_name.mp3.m3u.

[Doxer]

There is an error in your start-scripts.

It must be

Code: Select all

eend ${?}

and not

Code: Select all

eend $?

[darfsnuzal]

Doxer,

Thanks for the feedback. I was able to find only one other startup script (gpm) that used eend ${?} instead of eend $?. All of the other statup scripts I've examined used eend $?. Your thoughts?

Darf

[Doxer]

Sorry,
I take an existing scripts in my /etc/init.d as an example. There are brackest in the script. But, a look in an other script, there are no brackets

[darfsnuzal]

Cool! Thanks for double checking for me.

[atom]

Please post this howto on the wiki, as it will be easier to find and edit!

http://gentoo-wiki.com/HOWTO_Index

[georgebills]

Dest damn icecast howto I could find. (after spending a few hours following all the others.) The howto I was following told me to fill up my playlist with mp3s, and you (correctly) tell me that ices / icecast needs oggs. Thanks, this was awesome of you.

[igrat]

hi there,
had problems using your ices runscript:

i assume marked "--" is wrong...or did you mean to use another parm. ?

Code Listing 3.1: /etc/init.d/ices
...
start() {
ebegin "Starting ices"
start-stop-daemon --start --chuid icecast --quiet --exec /usr/bin/ices \
-- /home/icecast/ices-playlist.xml >/dev/null 2>&1
eend $?
}
...

good howto btw

greetings...

[atom]

hi there,
had problems using your ices runscript:

i assume marked "--" is wrong...or did you mean to use another parm. ?

the -- passes any following paramaters to the application being controlled by the start-stop-daemon, or to ices in this case.

[igrat]

next time i read the man

though i find my ices to die occasionally with exit status 0. (not backgrounded) Thats why i got confused.

i'll investigate....

[darfsnuzal]

Please post this howto on the wiki, as it will be easier to find and edit!

http://gentoo-wiki.com/HOWTO_Index

Good idea! I'll do that. This was my first howto so I wasn't sure what to do.

[darfsnuzal]

next time i read the man

though i find my ices to die occasionally with exit status 0. (not backgrounded) Thats why i got confused.

i'll investigate....

igrat - if you are still having trouble, post your ices log and I'll see if I can help you sort out your problem.

[darfsnuzal]

Dest damn icecast howto I could find. (after spending a few hours following all the others.) The howto I was following told me to fill up my playlist with mp3s, and you (correctly) tell me that ices / icecast needs oggs. Thanks, this was awesome of you.

You are very much welcome! I wrote this because of the same problem you ran into -- most of the howto's on the net are so out of date that they really no longer work. That's one of the downsides of the net...

[Niggurath]

im using muse and icecast , i get an error "shout_open: couldnt connect" and i think i m doing things as they should be but i just cant find what it is that error or what i'm doing wrong

[darfsnuzal]

Niggurath -

Did you get icecast working with ices before you tried muse? Start up icecast and the run muse from the command line. You can figure out which command line options you need by looking at /etc/init.d/muse. Does muse give any more errors when you start it like this? Are there any errors in /home/icecast/log/error.log?

An example muse command line would look like:

Code: Select all

muse -C /home/icecast/playlist.pls -o -e mp3 -b 128 -q 9 -r 44100 -c 2 -s localhost:8000 -m mymusic.mp3 -p $yourpass -g cli

Let us know.[/code]

[xlulux]

if your gonna do an icecast2 to an ices .3 to play mp3's you have to add the -t http (tell it what protocol to use ) or else it wont work, i fought with it for two days to make this work

nice tutorial

[igrat]

igrat - if you are still having trouble, post your ices log and I'll see if I can help you sort out your problem.

well...solved it...i had no r/w permission for the group icecast on the playlist.txt file...adding those worked fine

thanx anyways
igrat

[gondoi]

You know I was in the process of changing my startup script to use a conf.d file when it doned on me that the dependancy of ices to need icecast is not necessarily true...

What if a person is running icecast on another machine, but is running ices on a different one... Say maybe to use a smaller machine as the server and a workhorse to re-encode multiple streams.

Anyway, is there a way for startup scripts to check for other startup scripts.. say: if icecast is there then make sure it's started.... or whatever.

[gondoi]

I've got another question, Is there a way to make a startup script play nicely with a job that ends normally. Like say I set Ices to play through once and not loop. When it ends, I try to start it again with /etc/init.d/ices start, but it errors and tells me it's already running... but then if I do a /etc/init.d/ices stop, it tells me it's not.... or just gives me the [!!] same with the restart

anyone have an idea?

[kedalel]

hello
first thanks for this howto
but i still have a problem...
The songs playing with muse are playing too fast!!
with ices everything is ok
no error in the log file...

[gondoi]

The songs playing with muse are playing too fast!!

Hmmm... it sounds like a samplerate problem... is there a way to set it in muse? I think the value should be 44100

[kedalel]

/etc/conf.d/muse

Code: Select all

MUSE_BITRATE="128"
MUSE_QUALITY="9"
MUSE_RATE="44100"
MUSE_MOUNT="stream.mp3"
MUSE_ICECAST_SERVER="localhost:8000"
MUSE_ICECAST_PASSWD="**"
MUSE_PLAYLIST="/home/icecast/playlist.pls"
MUSE_LOG="/home/icecast/log/muse.log"

[igrat]

I've got another question, Is there a way to make a startup script play nicely with a job that ends normally. Like say I set Ices to play through once and not loop. When it ends, I try to start it again with /etc/init.d/ices start, but it errors and tells me it's already running... but then if I do a /etc/init.d/ices stop, it tells me it's not.... or just gives me the [!!] same with the restart

anyone have an idea?

well i guess in this case it ain't a daemon anymore

but you could still do a

Code: Select all

 /etc/init.d/ices zap 

to reset the ices start-stop daemon before starting again...

greetings...

[hegga]

hello
The songs playing with muse are playing too fast!!

I have this problem too, with the correct config file.
Does anyone have an solutions for this?

[kedalel]

same thing happening again and again...