Icecast Manual

Building
Configuring
1. Command line options
2. Configuration file (icecast.conf)
Running
1. Building
  This section describes where and how to download, unpack and compile your icecast system.
  I suggest you read it very carefully, especially the compiling chapter. Installing icecast is a simple procedure, and no special magic is involved.
  But to make the most of your icecast system, and understand the fundamental parts of the server and encoding streamers, it will help to know this chapter by heart.
  1. Downloading
    This section describes how to get the sources, or precompiled binaries, that you need to run icecast.
    There are some other tools that can help you broadcast, and in time, they will get listed here as well. To make a long story short, what you need to run an icecast system, is the icecast server, called icecast and an encoder (shout, liveice, winamp, iceplay, icesource).
    Some, like shout is usually included in the icecast packages. Others you'll have to download separately.
    1. Latest release
      When the icecast team thinks the development version is stable enough for the big public, they create a release. Example of releases are icecast-1.1.4, and icecast-1.3.0. Icecast versions follow the standard set by the linux kernel. Odd numbers are development releases, and even numbers are stable. So icecast 1.0 was stable, 1.1 was development, 1.2 would have been stable if we ever got around to releasing it, and 1.3 is development. When 1.3 is stable enough, we will call it 1.4 or perhaps 2.0 and move the development tree to 1.5 (or 2.1). A bit confusing.. I agree :)
      To get the latest release, go to www.icecast.org and click on downloads.
    2. Precompiled packages
      For some reason, people are lazy. Some people wants the system up and running without going through the compiling and compile time configuring stuff. That's why we supply precompiled packages in various formats for various platforms. We don't build all of these ourselves, but rely on other people to send them to us. If we can, we test them and make sure they work, but we offer no guarantees. For the big releases, such as 2.0, we hope to provide rpms, debs, and tarballs for most systems. If you build icecast for a platform for which there does not exist any precompiled packages, then it would be a great help for us if we could distribute that. Provided that it works :)
      You get the precompiled binaries at www.icecast.org, click on downloads.
    3. CVS (the cutting edge)
      Releases don't happen that often. We really try to keep them regular though, but there still might be a couple of months between the major ones. And I know some of you, like me, like to keep up with the absolutely latest source available. And the great thing is that you can :)
      Icecast developers use the CVS system to keep the source code in a separate repository so that all developers can use the same code at the same time (more or less).
      You too, can use CVS to get the latest sources. If you like to contribute to the sources, then notify team@icecast.org, and we'll add a cvs account for you. If you just want to get the sources, then get the cvs system from www.cyclic.com and follow this procedure:
      export CVSROOT='anonymous@cvs.icecast.org:/cvsroot'
      cvs login
      There is no password, just press enter.
      cvs -z3 checkout icecast
      And your done. Please note cvs sources are not stable, they change all the time and therefore might not build, or the server might crash. Also, you might note that there is no configure script, you need to use the ./autogen.sh script, that in runs automake, autoconf, configure and some other stuff.
      To keep an eye on icecast development, you can go to cvs.icecast.org and browse through the files, see the differences between the different versions, see what has been updated lately, and who's doing what.
      If you want a cross referenced html version of the whole icecast sourcetree, go to source.icecast.org.
    4. Snapshots
      For those of you who don't want to, or for some reason can't, use the cvs system, snapshots of the cvs modules are created once a day. Go to snapshots.icecast.org, and download the latest snapshot. The snapshots should have the configure script already set up for you.
  2. Unpacking
    Once you get the icecast system, you first need to unpack it. If you downloaded a release or a snapshot, then this is done by first gunzipping and then untarring the package, or if you're using GNU tar, then just do: tar -zxvf icecast-.tar.gz.
    If you've downloaded a precompiled package, then you hopefully know how to install it yourself :)
  3. Compiling
    This section describes how to compile the icecast system. Step by step instructions, and what options you have.
    If you just want the default setup, this is very simple. If you want to tailor the system for you specific needs, then this is very simple too.
    1. Creating the Makefile with configure
      In the toplevel icecast directory, there should be a file called configure.
      If there is not, but there is a file called ./autogen.sh, use this instead of ./configure.
      The configure script creates the Makefile. If you want the default setup, just run it with ./configure.
      There are three options to the configure script that you might want to enable.
      
      The first is --with-libwrap, which enables support for Wietse Venema's tcp wrappers. See the section about access control below.
      
      The second is --with-crypt, which means that the passwords you specify in icecast.conf, users.aut and on the command line when running the icecast server should be in encrypted form. To create these encrypted passwords, there's a program called mkpasswd included in the distribution.
      
      The third is --without-readline, which means that readline support, even if found, will not be used. You will not be able to use tab completion or command line editing on the icecast console.
      No other options to the configure script make any difference.
    2. Compile time settings
      This section describes what you can change in the Makefile, icetypes.h and icecast.h to optimize performance and change the default behavior of the icecast system. You do not have to go through this step if you just want the default setup.
      This step is optional.
      1. Editing the Makefile
        You need to edit the Makefile if you are not using gcc as compiler and want some compiler specific flags, or if you want to change some architecture specific compiler flags, e.g for optimization.
        The first two lines describe the compile being used (CC), and the compiler flags (CFLAGS). Change these to whatever is best on your system.
        For example, I use CC=gcc and CFLAGS= -O5 -march=i686 -mcpu=i686 -fstrict-aliasing.
      2. Editing icetypes.h
        The one single most important compile time setting for the icecast server is SOURCE_BUFFSIZE.
        It sets how many bytes will be read from the source before trying to send this chunk to the clients. It is by default set to 4096, because not all systems can read more than 4096 bytes in a single system call. If your server will take on a lot of listeners, or stream very high bitrate mpeg data, like video system mpeg streams, and if you system supports it, you should increase this value to 64 KiB or something similar.
        If you want a larger backlog for each client, which will allow for worse network congestion or other network errors before kicking the client, increase the CHUNKLEN value.
      3. Editing icecast.h
        Depending on which version of icecast you've got, there might be some extra defines you can set in icecast.h. For the 1.3.6 release, these are OPTIMIZE, SAVE_CPU, and some defines that only affect debugging.
        SAVE_CPU turns off tracing mutex locks and unlocks. This means you will not be able to track down a deadlock caused by bad mutex locking. But it will make your server use less cpu.
        OPTIMIZE will turn off a lot of debugging output, and it does make a lot of difference in cpu time. Think twice about defining this, cause when it is defined, you won't get any debug output from icecast at all, so when something goes wrong, you won't know.
        Combined, SAVE_CPU and OPTIMIZE might decrease cpu usage with up to 75%.
        DEBUG_MEMORY_MCHECK will (if mcheck.h is available) turn on malloc debugging. Probably only useful for developers.
        DEBUG_MUTEXES will turn on a lot of extra tracing and debugging for mutex locks. It will tell you when the server locks mutexes in a way that might deadlock the server, and lots of other stuff. This also, is only useful for developers.
        DEBUG_SOCKETS will activate the 'sock' command on the icecast console, which enables the user to list all open sockets, and close them if necessary. This can be kind of neat when a source is stuck in i/o and refuses to die. Closing the socket kills him for sure :)
        DEBUG_FULL will turn on all debugging and you can't turn it off again, it is turned on long before the command line or configfiles are parsed and is used to find errors early in the initialization phase.
    3. Compiling (running Make)
      Now it's time to run make. icecast has been developed using gnu make, and even if other makes might work, I would recommend using GNU Make.
      Type 'make' (or 'gmake'), and off we go. This will compile the icecast server.
      If you want the other icecast related tools, you'll have to download and install them separately.
      If you get any errors or warnings while compiling icecast, you should notify devel@icecast.org. We want the compilation procedure to be 100% clean on all platforms.
      Now type 'make install' (or 'gmake install'), and icecast will be installed. If you don't install icecast, it will probably not find the configuration files, templates, authorization files, but it will still work.
2. Configuring
  1. Command line options
    The following command line parameters can be given when you start the icecast server.
    Command line parameters override all configuration file parameters (icecast.conf), which in turn override the default compile time settings.
    - -c [filename]
      Parse as a configuration file. Please note that any command line parameters you supply after this override whatever is in file. Also note that icecast.conf in the current directory is already parsed when you specify this file, so anything in icecast.conf not overriden by the new configuration file will be used by the server.
    - -P [port]
      This is the port used for all client, source, and admin connections. It's set to 8000 by default.
    - -m [max clients]
      Allow this number of client connections. When this number is reached, all client connections will be refused with 'HTTP/1.0 504 Server Full'
    - -p [encoder password]
      This sets the password that the encoder must use to be allowed to stream to the server. Note that if you have compiled the server with crypt() support, this argument must be an encrypted string.
    - -b
      This will send the icecast server into the background (i.e daemon process). To use the admin commands now, you have to connect to the server as an admin, using some sort of telnet client.
    - -d [directory]
      Specifies the directory where icecast will look for configuration and authorization files.
    - -V
      Turn on full debugging.
  2. Configuration file (icecast.conf)
    This section describes the configuration parameters inside icecast main configuration file, icecast.conf. More information about the parameters can be found inside the icecast.conf file itself. Comments lines start with a '#' sign as the first character in the line, the rest of the line is ignored.
    Configuration parameters are specified as 'parametername parameter', where parametername is a string without spaces and parameter is the rest of the line.
    Never enclose the parameter in double quotes ("").
    Most of these parameters can be changed using the set command on the admin console.
    - encoder_password
      This is the password by which the server accepts encoders, metadata connections and pushing relays.
      You cannot connect to the server as an admin with this password.
    - admin_password
      The password needed for admins to be accepted to the admin console. Access to the WWW admin interface does not use this password, see the section about the WWW interface below.
    - oper_password
      This is the password an admin must specify to get access to the restricted server operator commands.
    - touch_freq
      This setting regulates how often the directory servers get 'touched' by the icecast server.
      The default setting of 5 minutes is a good value.
    - max_clients
      The maximum number of simultaneous clients connected to the server.
    - max_sources
      Max. number of simultaneous sources connected to the server.
    - max_admins
      Max. number of simultaneous connected admins. WWW admins are not affected since they are not interactively logged on.
    - logfile
      This file, icecast.log in /usr/local/icecast/log by default, is the icecast server's main logfile.
      Everything goes in here, so it might grow quite big. Also, when you restart the server, it will not truncate this file. So it might be a good idea to empty the file before each run of icecast. If it grows way to big, and you want to truncate it yourself, without restarting icecast, then you have to send icecast the SIGHUP signal so that it reopens the logfile.
      This means you can use common logrotating programs.
    - hostname
      You are probably better of leaving this setting alone. If NOT set, this will make icecast listen on all available interfaces (i.e all IPs), but if you set it to a hostname or IP adress, then icecast will only listen on that IP adress. This is nice for people with 2 ips who want to run one icecast server on each. If you specify an invalid IP, then nothing will work.
    - server_name
      This is perhaps the most important setting in icecast.conf. It's the name of the server. It SHOULD be set to an ip, or preferably a hostname that points to your ip. If not, then lots and lots of stuff will not work and it might even break your server. For instance, my ip is 130.236.235.105, which is d105.ryd.student.liu.se, so I set the server_name to d105.ryd.student.liu.se. See also the force_servername setting.
      When using aliases and in some cases multiple mountpoints, client have to request streams from this servername, otherwize they will not get the correct stream.
      For those of you familiar with virtual hosts in webservers, this is something similar :)
    - console_mode
      This sets how the icecast server is started, and what the tty you started icecast in will be used for.
      0 means use it as a admin console (you can send commands to the icecast server) with logfile info.
      1 is the same as 0 but without logfile info.
      2 means just use it as a logfile window.
      3 means put the icecast server in the background, as a daemon process.
      All console modes are not available on all platforms.
    - client_timeout
      This setting regulates how long (in seconds) to keep clients connected to the server after their source has disconnected. Or, in other words, how long to wait for a source to come back to its old listeners.
    - stats_log
      The icecast server dumps statistics to a file on a regular basis. See the section about statistics below.
      This sets what file is used for statistics.
    - statshtml_log
      This works just like stats_log, but the statistics are html-formatted, using the statistics.html template.
    - stats_time
      This setting, in seconds, sets how often the statistics files get updated.
    - max_clients_per_source
      The maximum number of simultaneous clients connected to the same stream on the server. Setting this to a value larger than max_clients does not make any sense.
    - reverse_lookups
      When this is set to 1, icecast will try to reverse all ips to hostnames. This might take some time and consume some extra cpu, but it will make logfiles and all other output look much nicer. Setting this to 0 will turn the reverse lookups off.
    - location
      This should be set to the geographic location of the icecast server. It's just for show, and doesn't really matter. But it's still a nice way for listeners to know where in the world the server is located.
      No syntactic controls apply, but if you want to follow the standard, use 'STATE, COUNTRY', or 'CITY, COUNTRY'.
    - rp_email
      This should be set to the email adress of the admin running the server.
    - transparent_proxy
      This should be set to 0 unless you really really know what you are doing. Setting it to 1 will make the icecast server act as a proxy. See the section about proxies below.
    - acl_policy
      This regulates whether connections are allowed or denied if no acl rule exists that affects them. See the section about Access Control below.
      Setting it to 0 will deny all these connections, and 1 will allow them.
    - throttle
      Specified in Megabytes per second. How much bandwidth the server is allowed to use up before client and source access is denied. Use this with caution since the internal bandwidth measurement is not an exact science.
    - kick_relays
      When a remote source is mounted into the icecast server on a remote alias request, it will only keep the source connected while there is still someone listening. When all listeners has disconnected, it will keep the source for kick_relays seconds, and then kick it out. This saves a lot of bandwidth.
    - kick_clients
      This regulates what happens to the clients when the client_timeout has expired. It only has an effect if client_timeout is more than 0. If you set kick_clients to 1, then they will get kicked off the server, but if you set it to 0, they will be moved to another stream, if there is one.
    - status_time
      This setting regulates how often status information is printed on the admin console.
    - staticdir
      If you don't want to go through the hassle of setting up a http server as a means of putting your mp3 files up for public download, then there is limited support for this in icecast. See the section about Static files below.
      This sets what directory on disk will be the root for http://your.server.com:port/file/
    - logfiledebuglevel
      This setting regulates what level of debugging output is written to the logfile. A higher value means more debugging output. 0 means no debugging output, 1 and 2 is pretty ok, 3 and 4 will spam it will shitload of stuff :). 6 is the current maximum.
    - consoledebuglevel
      This is the same as logfiledebuglevel, but regulates the output on the icecast console
    - server_url
      This should be set to a URL describing this icecast server.
    - use_meta_data
      This will enable title streaming the way shoutcast does it. This is old, stupid and will probably mess up your stream. Turn this off unless you really want it.
    - streamurl
      If the sources don't set a url for the stream, then this variable is the default url for titlestreaming.
    - streamurllock
      If you don't want the sources to be able to change the url of their streams, set this to 1.
    - streamtitletemplate
      This is a template for the stream title that is sent to the clients who support it, and to the directory servers. One occurence of "%s" will be replaced with the filename of the current song.
    - nametemplate
      This is a template for the name of each stream, as presented to the directory servers and clients. One occurence of "%s" will be replaced with the actual name of the stream.
    - desctemplate
      desctemplate is a template for the description string for each stream. One occurence of "%s" will be replaced with the actual description of the stream.
    - accessfile
      This file logs all the client connections to the server and should be parsable with any common logfile parser. It uses the same format as apache and other webservers.
    - usagefile
      This file is periodically updated with server usage information.
    - default_source_options
      This string is the default options for the 'sources' command.
    - mount_fallback
      Normally users who request a stream that is not found, they will get the default stream instead. When this is set to 0 they will get a HTTP 404 Stream Not Found instead.
    - force_servername
      The directory server will use the originating ip of the icecast server unless this is set to 1. If set to 1, this will make the directory server use the server_name variable instead. This is useful for people behind transparent proxies.
    - logdir
      This is the directory wherein logfiles are kept.
    - templatedir
      This is the directory where icecast looks for templates for the WWW admin and generation of stats.html.
    - resolv_type
      This variable regulates what kind of resolving functions icecast uses. Setting it to 1 means it will use linux reentrant interface (gethostbyname_r()), 2 means solaris reentrant interface, and 3 is the standard nonreentrant interface.
    - http_admin
      This setting regulates whether to allow access to the WWW interface at all. 1 means yes, 0 means no.
    - relay_reconnect_max
      This variable regulates how many times icecast will try to reconnect a relay. -1 means infinite times.
    - relay_reconnect_time
      This regulates how many seconds to wait between relay reconnect tries.
    - sleep_ratio
      This is a float variable that regulates how long a source thread in the server sleep between reading from the encoder. Setting it to a very low value will make the system use a little more cpu, and it might behave a little flaky with few listeners. Setting it to a very high value will probably make the audio very choppy. I.e few listeners, use a larger value, and with lots of listeners, use a smaller value. Anything larger than 1.0 and smaller than 0.0 is just pointless.
      Also, a fast cpu will be able to use a higher value than a slow cpu.
    - directory
      The syntax is 'directory directory.host.domain:port/path/to/icedir/program', or 'directory directory.host.domain:port', or 'directory directory.host.domain'. If not specified, the default port is 80, and the default icedir program is '/cgi-bin/xaudiocast-touch'
      Please note that this is the syntax for xaudiocast directory server. Some old directory servers use the old icy headers. If you want that, use the icydir command.
    - icydir
      This adds a icy directory server (such as yp.shoutcast.com). The syntax is simply 'icydir directory.host.domain'.
    - port
      This is the port the icecast server uses for all connections. Admins, clients, and sources, they all connect to this port. The old behavior, having the clients on 8000 and the encoder on 8001, is too ugly and creates some problems with firewalls and so. The new behavior might confuse streamers such as winamp. WinAMP is stupid enough to connect to the specified port + 1. So if you set the port (in WinAMP) to 8000, it will connect to 8001. Setting it to 7999 will work though.
      You can now use multiple ports, just add another port line.
      port 8000
      port 8001
      The above will make icecast listen on 8000 and 8001.
    - alias
      Aliases can be used for 2 things. One is for a very flexible and powerful way of relaying streams on other icecast or shoutcast servers. See the section about Relaying below. The other is for having 2 mountpoints on the server refer to the same source.
      'alias /cool /funkyassdancemusic' would add an alias named /cool which refers to the /funkyassdancemusic stream. It doesn't matter if no stream is actually mounted there now.
    - allow
      This adds a hostmask for a specific type connection, which will be allowed access. Syntax is 'allow [type] [hostmask]'.
      See the section below on Access Control.
    - deny
      This adds a hostmask for a specifi type connection, which will be refused access.
      Syntax is 'deny [type] [hostmask]'.
    - relay
      This works just like the relay pull command. Icecast will connect this relay at boot time, and reconnect it if it disconnects.
    - include
      This will parse another configfile.
      Ex: include /etc/defaulticecast.conf
3. Running
  This section describes and discusses the issues involved in running the icecast systems. Running clients, streamers, the admin console, and the server. It also takes up the various features of the system, such as access control, relaying, statistics, static files, etc...
  1. Client
    This chapter talks about the different clients you can use to connect and listen to a icecast stream. It tries to compare them, but to be honest, I haven't used them all and can only try to compare them using the information I have gathered from others.
    1. Windows clients
      - Sonique
        A very cool client for windows. People say its even more stable than winamp when it comes to streaming. And it looks damn cool :)
        Sonique supports xaudiocast titlestreaming.
      - K-Jofol
        Another really cool client, based on the mpg123 engine.
      - Winamp
        Developed by Nullsoft, Winamp is the most widely used mp3 player in the world. It is a stable audiocast client, and can also be used as a streamer. It does not (as of version 2.21) support x-audiocast headers, or titlestreaming, and probably never will.
    2. Unix clients
      - XMMS (formerly x11amp)
        A really cool mp3 player for Linux and FreeBSD (afaik). It has very stable streaming support, some support for x-audiocast headers and lots of more stream features.
      - mpg123
        Perhaps the most widely used mp3 player for unix. Command line driven, and with some limited support for audiocast streaming.
      - FreeAmp
        Getting more stable with every release, FreeAMP is also an option in the unix world.
    3. Mac clients
      - MacAST
      - SoundJam
  2. Source
    This section lists some of the ways you have of sending data to the icecast server. This is called streaming, and the program that handles this is called a streamer, or an encoder, or a source. They can be devided into two groups. Re-encoding streamers, and static file streamers.
    Static file streamers simply reads the bitrate of the file it is going to send, and transfers it to the server at that speed. To send a mp3 file encoded at 64 kbit/s, 64 kbit/s bandwidth will be required. This theory is quite simple, but actually keeping this exact bitrate is not that easy.
    Static streaming requires almost no amount of cpu or memory resources.
    The other category is re-encoding streamers, and they read the mp3 file, decodes it to wav or raw pcm data, and then encodes this at a specified bitrate. This way you can take a 128 kbit/s mp3 file, and send it at 24 kbit/s. This will require a substancial amount of cpu resources on your machine, but it is the only way of doing real DJ:ing with beatmixing and Mic input.
    1. shout
      Shout is a static file streamer with a powerful playlist engine and a finely tuned transfer loop.
      It has a large number of command line and configuration file parameters. Shout supports the new x-audiocast headers and is bundled with the icecast package. It supports titlestreaming of id3 tags and filename.
      Shout development has now stopped, and we've started over on a new streamer, called icesource. Complaints and bugreports for shout will be redirected to the large and hungry alligator hiding in /dev/null.
    2. liveice
      Liveice is a re-encoding streamer, also bundled with the icecast package. It is quite powerful and supports a number of different encoders (xing, fraunhofer, etc..). You can mix several mp3 streams and the mic input, change speed and volume of the different streams.
      For more info about liveice, including download location, go to the liveice webpage.
    3. iceplay
      iceplay is the ancient icecast pre 1.0 streamer. It's a static file streamer written in perl.
    4. winamp
      winamp is both a client and a streamer for Windows. It's a re-encoding streamer.
    5. icesource
      icesource is the new main icecast streamer. It's under development and not yet ready for the big masses.
      it uses the new source development library libshout.
  3. Admin
    This section describes the admin console, how to connect and what commands are available.
    1. Connecting the admin
      To access the admin console, telnet to your icecast server (port 8000 by default). You can use the default telnet client, but if you're planning on doing any serious work, I suggest you use a more sophisticated client such as TinyFugue. With TF you can get color highlighting and command line editing.
      When you connect, nothing will be printed, no prompt, nothing. Then you type the following:
      'ADMIN [admin password]' followed by two newlines (press enter twice). Substitute the [admin password] for the admin password you've set in icecast.conf or with a command line parameter to icecast.
    2. Commands
      The following commands are available in the icecast admin console. Most of them requires icecast operator access. To become an icecast operator, use the oper command with the operator password as an argument.
      - alias
        The alias command is used for two things. You can add an alias for a local mountpoint so that a stream can be accessed from two mountpoints. Or you can add an alias for a remote icecast/shoutcast stream. See the section about relaying using aliases below.
        Syntax:
        alias add <mountpoint> <newmountpoint> alias del <mountpoint> alias list New in 1.3.8 is the "whatever" keyword. If you specify the string 'whatever', without quotes of course, as the host of an alias, then it will match all hosts. This is useful for building generic aliases for certain mountpoints.
        Examples:
        alias add /icy_0 /coolstream alias add /radiofri http://195.7.65.207:6903/ alias add http://whatever/crappyfunk http://crappyfunk.com:8000/funk
This document is written by Alexander Hav�ng [eel@icecast.org].
Last modified: Fri Jun 9 15:07:34 CEST 2000